Skip to content

pk-doctor: agents_md_hygiene.managed-block-drift fires on pk-commands block that is by-design project-specific #80

@projectious

Description

@projectious

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:

  1. Skip pk-commands from byte-drift checking — only enforce the marker structure and the key set (`build`, `test`, `lint`, `fmt`, `typecheck`), not the content.
  2. Document and ship the exception mechanism (e.g. a key in `.processkit-provenance.toml` listing block IDs to skip).
  3. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions