docs: Correct dead paths and stale claims in repository instructions - #188
Merged
Merged
Conversation
The repository-specific instruction file accumulated references that no longer resolve against the repository, so an agent following them lands on nothing or on a wrong answer. - The migration guide was cited as `docs/migration/v0.8-to-v1.0.md`. The file on disk is `docs/migration-v0.8-to-v1.0.md` - a hyphen, not a directory separator, so the path does not exist. - The consumer psake example set `$PSBPreference.Test.ScriptAnalysisEnabled`. No such setting exists; `build.properties.ps1` defines the nested `$PSBPreference.Test.ScriptAnalysis.Enabled`, which is also what the README settings table documents. - The Test workflow section described a matrix, a build command, and a `DEBUG` runner flag inside `.github/workflows/test.yml`. Commit c2c184e replaced all of that with a delegation to the psake organization's shared `ModuleCI.yml`, and the `DEBUG` flag no longer exists anywhere. The section now points at the shared workflow that actually holds the matrix and the command. - `Get-PSBuildHelpLocale` was missing from the private helper list, which named `Remove-ExcludedItem` as the only one. - The test file table listed five of the sixteen test files, and described `Meta.tests.ps1` as script analysis when it tests text file encoding and indentation. - The output directory example pinned version `0.8.0` while the manifest reads `0.8.2`. It now shows `<ModuleVersion>` so it cannot drift again. Only `repository-specific.instructions.md` is edited. Every other file in `instructions/` is synced from the AIM template repository, which `update.instructions.md` confirms never copies this one from upstream, so local edits there would be reverted on the next sync. The audit found no defects in the synced files. The `Last sync` date in `AGENTS.md` is left alone because `update.instructions.md` sets it only during a sync. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE
This was referenced Aug 27, 2026
README examples assign a setting that does not exist: $PSBPreference.Test.ScriptAnalysisEnabled
#191
Closed
tablackburn
added a commit
that referenced
this pull request
Aug 28, 2026
instructions/repository-specific.instructions.md keeps a table of every test file and what it covers. #188 corrected that table when it listed 5 of 15 files; adding a test file without adding a row puts it straight back out of date. Caught by the code review of this pull request. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE
tablackburn
added a commit
that referenced
this pull request
Aug 28, 2026
instructions/repository-specific.instructions.md keeps a table of every test file and what it covers. #188 corrected that table when it listed 5 of 15 files; adding a test file without adding a row puts it straight back out of date. Caught by the code review of this pull request. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE
tablackburn
added a commit
that referenced
this pull request
Aug 28, 2026
The test-file table in repository-specific.instructions.md was corrected in #188, which found it listing 5 of the 15 files that existed. #187 then added tests/LocalizedData.tests.ps1 without adding a row -- the same omission, one merge later. Folded into this documentation-only pull request rather than opened separately because it is a single row in a table two sibling pull requests are already amending, and leaving it would mean the table is wrong again the moment they land. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE
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 free
to 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.
Summary
instructions/repository-specific.instructions.mdhad accumulated references that no longerresolve against the repository. An agent following them lands on nothing, or on a wrong answer.
This corrects them and audits the rest of the file and
AGENTS.mdfor the same class of defect.Repository-owned fixes (this PR)
instructions/repository-specific.instructions.mdis the only file changed. Evidence for each fix:docs/migration/v0.8-to-v1.0.mdls docs/returns exactly one file,migration-v0.8-to-v1.0.md. A hyphen, not a directory separator$PSBPreference.Test.ScriptAnalysisEnabledPowerShellBuild/build.properties.ps1line 64 defines the nestedScriptAnalysis = @{ Enabled = ... }.README.mdline 108 documents it as$PSBPreference.Test.ScriptAnalysis.Enabled.ScriptAnalysisEnabledis read by nothing in the module./build.ps1 -Task Test -Bootstrapcommand, and aDEBUGrunner flag.github/workflows/test.ymlis 20 lines and defines one job that isuses: psake/.github/.github/workflows/ModuleCI.yml@main. Commitc2c184ereplaced the inline job with that delegation.grep -rn DEBUG .github/returns nothingRemove-ExcludedItemnamed as the private helperPowerShellBuild/Private/also containsGet-PSBuildHelpLocale.ps1Meta.tests.ps1script analysistests/contains sixteen*.tests.ps1files.Meta.tests.ps1has oneDescribe 'Text files formatting'withFile encodingandIndentationscontexts, and invokes no analyzer0.8.0/ModuleVersionin the manifest is0.8.2. Replaced with<ModuleVersion>so it cannot drift againOwnership: what was not touched, and why
instructions/update.instructions.mdstates under Content Preservation Rules that"the file
repository-specific.instructions.mdmust NEVER be copied from upstream", andcontributing.instructions.mdstates "local changes belong inrepository-specific.instructions.md- this file is never synced from upstream". The othereleven files in
instructions/are listed inaim.config.jsonundermodules.includeand arecopied from the AIM template's
instruction-templates/folder on each sync, so a local edit toany of them is silently reverted at the next sync.
The audit found no defects in the synced files. They contain no claims about this repository:
grepforPowerShellBuild,PlatyPS,AlphabeticParamsOrder,requirements,docs/,tests/, and.github/across them returns only generic guidance and hypothetical examples.Nothing needs an upstream contribution.
The
Last syncdate inAGENTS.mdis unchanged.update.instructions.mdstep 8 sets that fieldonly as part of a sync from the centralized repository, and this is not a sync.
Also verified clean
requirements.pester-matrix.psd1:grepacrossinstructions/,AGENTS.md, andCLAUDE.mdfinds no reference to the deleted file.and
Microsoft.PowerShell.PlatyPS1.x are all already stated correctly and matchrequirements.psd1andPowerShellBuild.psd1.$PSB{TaskName}Dependencyvariables, and all 12 exported functions named in the file exist withthe stated defaults.
AGENTS.mdmatrix: all 12 files it routes to exist, and all 12 files ininstructions/appear in it. No gaps in either direction.
build.ps1flags:-Bootstrap,-Task,-Help, and-PSGalleryApiKeyall exist as documented.Out of scope, reported not fixed
README.mdlines 171 and 198 carry the same$PSBPreference.Test.ScriptAnalysisEnablederror theinstruction file copied, contradicting the README's own settings table 60 lines above. That is
user-facing documentation and belongs in its own pull request.
Test plan
./build.ps1 -Task Test- 483 passed, 0 failed, 3 skipped, matching the baselinethe repository rather than read for plausibility
Breaking changes
None. Internal agent documentation only, so no CHANGELOG entry.
Note on PR #186
Branch
docs/readme-alphabeticparamsorder-driftalso edits this file, removingAlphabeticParamsOrderfrom theDocssettings row at line 75. That row is untouched here andthe two changes are on disjoint lines.
🤖 Generated with Claude Code
https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE