Skip to content

docs: Correct dead paths and stale claims in repository instructions - #188

Merged
tablackburn merged 1 commit into
mainfrom
docs/fix-stale-agent-instruction-references
Aug 27, 2026
Merged

docs: Correct dead paths and stale claims in repository instructions#188
tablackburn merged 1 commit into
mainfrom
docs/fix-stale-agent-instruction-references

Conversation

@tablackburn

Copy link
Copy Markdown
Contributor

Summary

instructions/repository-specific.instructions.md had accumulated references that no longer
resolve 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.md for the same class of defect.

Repository-owned fixes (this PR)

instructions/repository-specific.instructions.md is the only file changed. Evidence for each fix:

Was Evidence it is wrong
Migration guide cited as docs/migration/v0.8-to-v1.0.md ls docs/ returns exactly one file, migration-v0.8-to-v1.0.md. A hyphen, not a directory separator
Consumer example set $PSBPreference.Test.ScriptAnalysisEnabled PowerShellBuild/build.properties.ps1 line 64 defines the nested ScriptAnalysis = @{ Enabled = ... }. README.md line 108 documents it as $PSBPreference.Test.ScriptAnalysis.Enabled. ScriptAnalysisEnabled is read by nothing in the module
Test workflow described as having a matrix, a ./build.ps1 -Task Test -Bootstrap command, and a DEBUG runner flag .github/workflows/test.yml is 20 lines and defines one job that is uses: psake/.github/.github/workflows/ModuleCI.yml@main. Commit c2c184e replaced the inline job with that delegation. grep -rn DEBUG .github/ returns nothing
Remove-ExcludedItem named as the private helper PowerShellBuild/Private/ also contains Get-PSBuildHelpLocale.ps1
Test file table listed five files, and called Meta.tests.ps1 script analysis tests/ contains sixteen *.tests.ps1 files. Meta.tests.ps1 has one Describe 'Text files formatting' with File encoding and Indentations contexts, and invokes no analyzer
Output directory example pinned 0.8.0/ ModuleVersion in the manifest is 0.8.2. Replaced with <ModuleVersion> so it cannot drift again

Ownership: what was not touched, and why

instructions/update.instructions.md states under Content Preservation Rules that
"the file repository-specific.instructions.md must NEVER be copied from upstream", and
contributing.instructions.md states "local changes belong in
repository-specific.instructions.md - this file is never synced from upstream". The other
eleven files in instructions/ are listed in aim.config.json under modules.include and are
copied from the AIM template's instruction-templates/ folder on each sync, so a local edit to
any 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:
grep for PowerShellBuild, PlatyPS, AlphabeticParamsOrder, requirements, docs/,
tests/, and .github/ across them returns only generic guidance and hypothetical examples.
Nothing needs an upstream contribution.

The Last sync date in AGENTS.md is unchanged. update.instructions.md step 8 sets that field
only as part of a sync from the centralized repository, and this is not a sync.

Also verified clean

  • requirements.pester-matrix.psd1: grep across instructions/, AGENTS.md, and
    CLAUDE.md finds no reference to the deleted file.
  • Recent dependency moves: the psake 5.0.4 floor, the Pester 6.0.0 module floor and 6.1.0 pin,
    and Microsoft.PowerShell.PlatyPS 1.x are all already stated correctly and match
    requirements.psd1 and PowerShellBuild.psd1.
  • Task and settings names: all 17 module-level tasks, all 8 repository-level tasks, all 15
    $PSB{TaskName}Dependency variables, and all 12 exported functions named in the file exist with
    the stated defaults.
  • AGENTS.md matrix: all 12 files it routes to exist, and all 12 files in instructions/
    appear in it. No gaps in either direction.
  • build.ps1 flags: -Bootstrap, -Task, -Help, and -PSGalleryApiKey all exist as documented.

Out of scope, reported not fixed

README.md lines 171 and 198 carry the same $PSBPreference.Test.ScriptAnalysisEnabled error the
instruction 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 baseline
  • Every path, task name, setting name, and function name asserted in the file checked against
    the 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-drift also edits this file, removing
AlphabeticParamsOrder from the Docs settings row at line 75. That row is untouched here and
the two changes are on disjoint lines.

🤖 Generated with Claude Code

https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE

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
Copilot AI lite review requested due to automatic review settings August 27, 2026 19:15

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@github-actions

Copy link
Copy Markdown

Test Results

    4 files  ±0    760 suites  ±0   2m 29s ⏱️ +10s
  485 tests ±0    482 ✅ ±0   3 💤 ±0  0 ❌ ±0 
1 944 runs  ±0  1 877 ✅ ±0  67 💤 ±0  0 ❌ ±0 

Results for commit e49f979. ± Comparison against base commit a64ebc8.

@tablackburn
tablackburn merged commit 14003c0 into main Aug 27, 2026
9 checks passed
@tablackburn
tablackburn deleted the docs/fix-stale-agent-instruction-references branch August 27, 2026 22:28
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants