Skip to content

Teach the engine the template-owned files added through project-template v0.53.0 #148

Closed

Description

@polewskm

workflowCommands, templateFiles and templateFolders in src/template.ts, and the README's "Template-owned files" section, still list v0.41.1's set plus audit-conventions, so findings on docs/decisions/project-template/, .github/workflows/template-update.yml, .github/workflows/code-review-auto-merge.yml, csharp-tests instructions and the .NET build/ files (dod.ps1, *.globalconfig, BannedSymbols.txt, Update-PublicApi.ps1) in repositories on newer template versions are posted as the project's instead of moved upstream.

Found while planning Update from project-template v0.53.0; it landed in #147.

Activity

  1. polewskm commented on Nov 1, 2026

    @polewskm
    ContributorAuthor

    Plan snapshot. The working copy is PLAN.md in the plan's checkout; this comment is not updated as steps run.

    Plan: Teach the engine the template's newer owned files (4 steps)

    Plan: Teach the engine the template's newer owned files

    Issue: #148

    Goal

    In a pull request that adopts or updates NCodeGroup/project-template, the engine moves findings on template-owned files upstream instead of posting them as threads. Its fixed list in src/template.ts still stops at v0.41.1 plus audit-conventions, so files the template added and replaces on every update since then (its decision records, two workflows, the C# test rules and the .NET build/ files) are reviewed as the project's. This plan adds them, through v0.54.0, the template's newest release, and brings the README's "Template-owned files" section up to date.

    Context for the executor

    • Build: npm run typecheck
    • Test: npm test (the full suite takes several minutes; each step's Done-when runs only test/template.test.ts)
    • Conventions: Node 24, TypeScript run directly (node file.ts), strict tsconfig.json. Tests use node:test and node:assert/strict in test/*.test.ts, one behavior per test, hermetic. Comments explain why, in full sentences. Keep lines at most 120 characters, as the existing code does. UTF-8 without BOM, LF line endings.
    • Gotchas: node_modules is already installed in this worktree (npm ci). When node or npm isn't on PATH in your shell, run . "$env:LOCALAPPDATA\nvs\nvs.ps1" use 24 once in that shell first; never put that into a Done-when command. isTemplateOwned(file, template) in src/template.ts is only a name rule: src/gather.ts asks it only in a pull request that adopts or updates the template, and src/template-check.ts then confirms each named file against the template's own copy, so a file edited by hand stays the project's whatever the list says. templateFolders entries are path prefixes ending in /.

    Decisions

    • Root cause: workflowCommands, copilotAgents, templateFiles and templateFolders in src/template.ts are a fixed list written for project-template v0.41.1, and only audit-conventions was added since. The guard test isTemplateOwned covers every generated file this repository has from the template scans only .template, .githooks, .claude/commands, .claude/agents, .github/prompts, .github/skills and .github/agents, and this repository is a Node project, so neither docs/decisions/project-template/, the template's workflows nor its .NET-only files could make it fail. Evidence: on the unchanged code, isTemplateOwned returns false for docs/decisions/project-template/0001-conventions-and-lessons-live-in-the-repository.md, .github/workflows/template-update.yml, .github/workflows/code-review-auto-merge.yml, build/dod.ps1 and .claude/rules/csharp-tests.md.
    • The template-owned set at v0.53.0 was taken from the template itself: every file git ls-tree -r --name-only v0.53.0 -- template/ renders, minus copier.yml's _skip_if_exists and _merged_files and the answers file. The ones the engine misses are: the folder docs/decisions/project-template/, .github/workflows/template-update.yml, .github/workflows/code-review-auto-merge.yml, .github/instructions/csharp-tests.instructions.md, .claude/rules/csharp-tests.md, build/ProjectTemplate.globalconfig, build/ProjectTemplate.Tests.globalconfig, build/BannedSymbols.txt, build/dod.ps1 and build/Update-PublicApi.ps1. v0.54.0 only changes the three run-issues files, so the list holds through v0.54.0, and the code and README say so.
    • docs/decisions/project-template/ goes into templateFolders as a prefix, like .template/: the template owns the whole folder, adds a record to it in most releases, and renders .NET-only records into it, so naming files would go stale again. A file a project adds there itself isn't in the template's copy, so the template check leaves it the project's.
    • The two workflows are named one by one: the rest of .github/workflows/ is the project's (code-review.yml, publish.yml) or merged (ci.yml, copilot-setup-steps.yml).
    • The guard test now also scans docs/decisions/project-template and names the two workflows, which this repository has as the template's exact copies at v0.53.0. The .NET-only files can't be scanned here, so the new regression test names them.
    • The engine keeps its fixed list rather than deriving the set from the template's copier.yml: that changes how readChanges and confirmTemplateFiles work and is listed as a follow-up.
    • The review prompt's templateBlock in src/review.ts says the files a project merges include "the workflows". Two workflows are now template-owned, so it names the merged ones, ci.yml and copilot-setup-steps.yml.
    • This is a fix of stale data, not a new interface, so it needs no ADR, and release is none, so the plan has no Release: line.

    Out of scope

    • Don't change src/gather.ts, src/template-check.ts, renderedTemplatePaths, matchesTemplateSource or how the template check confirms files.
    • Don't derive the list from the template at run time, and don't add a network read to any test.
    • Don't edit guidance/, training/ or evals/, even where they name template files.
    • Don't touch workflowCommands or copilotAgents, and don't remove any name already in templateFiles.
    • Don't edit the template's own files in this repository (.template/, docs/decisions/project-template/, .github/workflows/template-update.yml, .github/workflows/code-review-auto-merge.yml, generated commands, prompts, skills, agents).
    • Don't reword other README sections or other changelog entries.

    Steps

    [ ] 1. Add a regression test for the template's newer files

    • Files: test/template.test.ts (edit)
    • Change: Add one test right after the test 'isTemplateOwned covers the files the template replaces, and none the project owns or merges' (it ends with assert.ok(!isTemplateOwned('.template/Get-PlanState.ps1', undefined)); and });), before the comment // This repository is made from the template, .... Name it exactly 'isTemplateOwned covers the files the template added through v0.54.0'. Put a one-line comment above it: // project-template v0.42.0 to v0.53.0 added these files, and replaces them on every update; v0.54.0 added none. The test:
      • asserts isTemplateOwned(file, template) with file as the message for each of: docs/decisions/project-template/0001-conventions-and-lessons-live-in-the-repository.md, docs/decisions/project-template/README.md, docs/decisions/project-template/0100-warnings-are-errors-in-every-project.md, .github/workflows/template-update.yml, .github/workflows/code-review-auto-merge.yml, .github/instructions/csharp-tests.instructions.md, .claude/rules/csharp-tests.md, build/ProjectTemplate.globalconfig, build/ProjectTemplate.Tests.globalconfig, build/BannedSymbols.txt, build/dod.ps1, build/Update-PublicApi.ps1;
      • after the comment // The project's own decisions and the files the template writes once or merges next to them stay the project's., asserts !isTemplateOwned(file, template) with file as the message for each of: docs/decisions/README.md, docs/decisions/0000-template.md, docs/decisions/1000-use-postgres.md, docs/decisions/project-template-notes.md, .github/workflows/copilot-setup-steps.yml, .github/workflows/publish.yml, .github/workflows/release.yml, build/env.ps1, Directory.Build.props, CONTRIBUTING.md, SECURITY.md, docs/README.md;
      • finally asserts !isTemplateOwned('build/dod.ps1', { ...template, projectOwned: ['build/dod.ps1'] }).
    • Pattern: the for (const file of [...]) { assert.ok(isTemplateOwned(file, template), file); } loops in the test before it, and its projectOwned assertion.
    • Done when: node --test --test-skip-pattern "added through v0.54.0" test/template.test.ts; if ($LASTEXITCODE) { exit 1 }; node --test --test-name-pattern "added through v0.54.0" test/template.test.ts; if ($LASTEXITCODE) { exit 0 } else { exit 1 }

    [ ] 2. List the newer files as template-owned

    • Files: src/template.ts (edit), test/template.test.ts (edit), src/review.ts (edit)
    • Change:
      • src/template.ts: set const templateFolders = ['.template/', 'docs/decisions/project-template/'];. In templateFiles, after '.claude/rules/csharp.md', add '.claude/rules/csharp-tests.md', and '.github/instructions/csharp-tests.instructions.md',; after 'build/ProjectTemplate.props', add 'build/ProjectTemplate.globalconfig',, 'build/ProjectTemplate.Tests.globalconfig',, 'build/BannedSymbols.txt',, 'build/dod.ps1',, 'build/Update-PublicApi.ps1',, '.github/workflows/template-update.yml', and '.github/workflows/code-review-auto-merge.yml',. In the header comment, after the sentence ending so its findings are posted rather than hidden., add (wrapped at 120 characters, each line starting // ): The list follows the template through v0.54.0: when a release adds a file, list each one its template/ folder renders that copier.yml doesn't name under _skip_if_exists or _merged_files. Also change `.template/` and the files below in that comment to `.template/`, `docs/decisions/project-template/` and the files below.
      • test/template.test.ts, test 'isTemplateOwned covers every generated file this repository has from the template': add 'docs/decisions/project-template' to the end of the folder list that is .flatMap(files)-ed, and make generated that list followed by '.github/workflows/template-update.yml' and '.github/workflows/code-review-auto-merge.yml' (for example const generated = [...[...folders].flatMap(files), '.github/workflows/template-update.yml', '.github/workflows/code-review-auto-merge.yml'];, keeping the folder list inline). Add to the comment above the test: The template's workflows are named, since the project's own share their folder.
      • src/review.ts, function templateBlock: replace the text (such as .gitignore, .gitattributes, editor and tool settings and the workflows) with (such as .gitignore, .gitattributes, editor and tool settings, ci.yml and copilot-setup-steps.yml).
    • Pattern: the existing entries of templateFiles and templateFolders.
    • Done when: npm run typecheck; if (-not $? -or $LASTEXITCODE) { exit 1 }; node --test test/template.test.ts; if (-not $? -or $LASTEXITCODE) { exit 1 }; if ((Select-String -LiteralPath test/template.test.ts -SimpleMatch 'added through v0.54.0' -Quiet) -and (Select-String -LiteralPath src/review.ts -SimpleMatch 'editor and tool settings, ci.yml and copilot-setup-steps.yml)' -Quiet) -and (Select-String -LiteralPath src/template.ts -SimpleMatch 'through v0.54.0' -Quiet)) { exit 0 } else { exit 1 }

    [ ] 3. Describe the newer files in the README

    • Files: README.md (edit)
    • Change: In the section ### Template-owned files, replace the paragraph text from NCodeGroup/project-template, these files are template-owned, except any that through settings, \ci.yml`, `dependabot.yml`) and the answers file.(the end of the first paragraph) with this text, wrapped at about 120 characters like the lines around it: ``NCodeGroup/project-template, these files are template-owned, as of its v0.54.0, except any thatproject_owned_fileslists: everything under.template/anddocs/decisions/project-template/, the template's hooks (.githooks/commit-msgandpre-push), its generated commands, prompt files, skills and agents in .claude/commands/, .claude/agents/, .github/prompts/, .github/skills/and.github/agents/, CLAUDE.md, .template-version, .github/instructions/project-template.instructions.md, its C# rules (.github/instructions/csharp.instructions.md, .github/instructions/csharp-tests.instructions.md, .claude/rules/csharp.mdand.claude/rules/csharp-tests.md), its workflows template-update.ymlandcode-review-auto-merge.yml, and its .NET files in build/ (ProjectTemplate.props, ProjectTemplate.globalconfig, ProjectTemplate.Tests.globalconfig, BannedSymbols.txt, dod.ps1andUpdate-PublicApi.ps1). A file a later template version adds is the project's until the engine lists it. Everything else is the project's, including a command, prompt, skill, agent or hook it adds under a name the template doesn't use, the files the template writes once (AGENTS.md, README.md, CONTRIBUTING.md, SECURITY.md, code-review.yml, docs/decisions/README.md), the files it merges with the project's (.gitignore, .gitattributes, the settings, ci.yml, copilot-setup-steps.yml, dependabot.yml) and the answers file.`` The text before it in the paragraph (from A repository made fromtoWhen `_src_path` names`) stays as it is.
    • Pattern: the wrapping of the paragraph's other lines.
    • Done when: $t = (Get-Content -Raw README.md) -replace '\s+', ' '; if ($t.Contains('everything under .template/anddocs/decisions/project-template/') -and $t.Contains('its workflows template-update.ymlandcode-review-auto-merge.yml') -and $t.Contains('BannedSymbols.txt, dod.ps1andUpdate-PublicApi.ps1)') -and $t.Contains('ci.yml, copilot-setup-steps.yml, dependabot.yml) and the answers file.') -and -not $t.Contains('.claude/rules/csharp.mdandbuild/ProjectTemplate.props. Everything else')) { exit 0 } else { exit 1 }

    [ ] 4. Record the fix in the changelog

    • Files: CHANGELOG.md (edit)
    • Change: Under ## [Unreleased], in its existing ### Fixed group (don't add a second ### Fixed heading), add this bullet after the existing bullet that ends ([#133](https://github.com/NCodeGroup/code-review/issues/133)).:
      - In a pull request that adopts or updates project-template, a finding on a file the template added through v0.54.0 and replaces on every update moves upstream to NCodeGroup/project-template like a finding on its other files, instead of being posted as the project's: its decision records in `docs/decisions/project-template/`, its `template-update.yml` and `code-review-auto-merge.yml` workflows, its C# test rules (`.github/instructions/csharp-tests.instructions.md` and `.claude/rules/csharp-tests.md`) and its .NET `build/` files (`ProjectTemplate.globalconfig`, `ProjectTemplate.Tests.globalconfig`, `BannedSymbols.txt`, `dod.ps1` and `Update-PublicApi.ps1`) ([#148](https://github.com/NCodeGroup/code-review/issues/148)).
      Keep the bullet on one line, like the others. Change nothing else in the file.
    • Pattern: the ### Fixed bullet for Confirm the scheduling and caching gains in production traces #133 above it.
    • Done when: $t = (Get-Content -Raw CHANGELOG.md) -split '(?m)^## \[1\.0\.0\]'; if ($t[0].Contains('Update-PublicApi.ps1) ([#148](https://github.com/NCodeGroup/code-review/issues/148)).') -and ([regex]::Matches($t[0], '(?m)^### Fixed$').Count -eq 1)) { exit 0 } else { exit 1 }

    Review checklist

    • templateFiles keeps every name it had, and docs/decisions/project-template/ ends with /, so docs/decisions/project-template-notes.md isn't matched.
    • A file a project adds in docs/decisions/project-template/ itself, or edits there by hand, stays the project's in a template update pull request, because confirmTemplateFiles finds no matching copy in the template.
    • npm test passes in full, not just test/template.test.ts, including the review and engine tests that build the prompt with templateBlock.
    • The README paragraph reads as one paragraph, wrapped like the lines around it, and the changelog's ## [Unreleased] has one ### Fixed heading.

    Follow-ups

    • Derive the template-owned files from the template's copier.yml: src/template.ts hard-codes the files NCodeGroup/project-template replaces, so each template release that adds one (v0.42.0 to v0.53.0 added ten, Teach the engine the template-owned files added through project-template v0.53.0 #148) has its findings posted as the project's until an engine release lists it; in an adoption or update pull request confirmTemplateFiles in src/template-check.ts already reads the template's tree at _commit, so it could also read copier.yml's _skip_if_exists and _merged_files there and treat every other file the template/ folder renders as template-owned.
  2. polewskm commented on Nov 2, 2026

    @polewskm
    ContributorAuthor

    Follow-ups filed from this plan: #152 Derive the template-owned files from the template's copier.yml

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    follow-upWork a plan found and did not do

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions