Summary
`pk-doctor`'s `agents_md_hygiene.managed-block-drift` check WARNs when a managed block in `AGENTS.md` doesn't byte-match the upstream template — but the `pk-commands` block is itself designed to be project-customized (it's the project command adapter where derived projects fill in their own `build`/`test`/`lint` commands). The check's own metadata calls it "project command adapter block".
Repro (ai-market-research, just upgraded to v0.27.1)
Local AGENTS.md `pk-commands` block:
```
build: "bash src/scripts/build.sh"
test: "bash src/scripts/release-check.sh"
```
Upstream v0.27.1 template AGENTS.md:
```
build: "npm --prefix docs-site run build"
test: "uv run scripts/smoke-test-servers.py"
```
Doctor reports:
```
WARN agents_md_hygiene.managed-block-drift
AGENTS.md managed block 'pk-commands' differs from
context/templates/processkit/v0.27.1/AGENTS.md
suggested_fix: "replace the managed block from the current processkit source
unless the project records an explicit exception"
```
Following the suggested_fix would break the local project's build/test pointers, replacing them with upstream's own `npm` / `smoke-test-servers.py` commands.
The suggested_fix mentions "unless the project records an explicit exception" but I can find no documented exception mechanism in the codebase.
Expected
One of:
- Skip pk-commands from byte-drift checking — only enforce the marker structure and the key set (`build`, `test`, `lint`, `fmt`, `typecheck`), not the content.
- Document and ship the exception mechanism (e.g. a key in `.processkit-provenance.toml` listing block IDs to skip).
- Don't ship a populated pk-commands block in the upstream template — leave it empty so any project customization is the source of truth.
Impact
False-positive WARN on every derived project that customizes commands (i.e. all of them). `pk-doctor` cannot go clean. Mechanically following the suggested_fix actively breaks projects.
Related
Summary
`pk-doctor`'s `agents_md_hygiene.managed-block-drift` check WARNs when a managed block in `AGENTS.md` doesn't byte-match the upstream template — but the `pk-commands` block is itself designed to be project-customized (it's the project command adapter where derived projects fill in their own `build`/`test`/`lint` commands). The check's own metadata calls it "project command adapter block".
Repro (ai-market-research, just upgraded to v0.27.1)
Local AGENTS.md `pk-commands` block:
```
build: "bash src/scripts/build.sh"
test: "bash src/scripts/release-check.sh"
```
Upstream v0.27.1 template AGENTS.md:
```
build: "npm --prefix docs-site run build"
test: "uv run scripts/smoke-test-servers.py"
```
Doctor reports:
```
WARN agents_md_hygiene.managed-block-drift
AGENTS.md managed block 'pk-commands' differs from
context/templates/processkit/v0.27.1/AGENTS.md
suggested_fix: "replace the managed block from the current processkit source
unless the project records an explicit exception"
```
Following the suggested_fix would break the local project's build/test pointers, replacing them with upstream's own `npm` / `smoke-test-servers.py` commands.
The suggested_fix mentions "unless the project records an explicit exception" but I can find no documented exception mechanism in the codebase.
Expected
One of:
Impact
False-positive WARN on every derived project that customizes commands (i.e. all of them). `pk-doctor` cannot go clean. Mechanically following the suggested_fix actively breaks projects.
Related