## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - GitHub Actions builds the Docker images that ship Paperclip, and the
image build re-runs the runner's committed-artifact checks.
> - PR #12855 restored the capability-contract files that PR #12769's
context slimming stripped, and image builds then progressed one step
further in the chain.
> - The next check, `check:runner-workflow-traceability`, access()es
every regression test its spec names — `src/**/*.test.ts` files that the
same slimming block also strips.
> - Every image build since #12855 merged now fails there with ENOENT,
so image publishing is still down.
> - This pull request restores those files with one more narrow
exception and teaches the context probe to derive the required paths
from the spec itself.
> - The benefit is that image publishing recovers, and the probe now
covers this input class without a hand-maintained path list that could
rot.
## Linked Issues or Issue Description
Refs #12855 (first restoration from the same incident) and #12769 (the
context-slimming change).
**What happened?**
After #12855 merged, every `Docker` workflow run on master still failed,
now inside `check:runner-workflow-traceability`: `Error: ENOENT ...
access
'/app/packages/paperclip-runner/src/contracts/native-execution.test.ts'`.
The check access()es all 29 regression tests named by
`spec/evals/stress-workflow-traceability.json`; they are
`src/**/*.test.ts` files, and the
`packages/paperclip-runner/**/*.test.ts` ignore rule strips them from
the build context.
**Expected behavior**
The Docker build context must contain every file the image build reads.
The context-integrity probe must catch this class on the pull request,
including inputs named dynamically by a spec.
**Steps to reproduce**
1. Check out master after #12855.
2. Run `docker buildx build -f .github/docker-context-checks.Dockerfile
.` with this PR's probe, or the real `Docker` workflow build.
3. Observe the ENOENT above; with this PR's `.dockerignore` exception,
both pass.
**Paperclip version or commit**
`bb920fb8` (first post-#12855 failing image build) through master tip.
**Deployment mode**
GitHub Actions image builds (`docker.yml`), consumed by managed cloud
deployments.
## What Changed
- `.dockerignore`: re-include
`packages/paperclip-runner/src/**/*.test.ts` and `.tsx` — the
traceability spec references only files under `src`, so the remaining
test exclusions stay.
- `.github/docker-context-checks.Dockerfile`: new spec-driven existence
walk that replicates the traceability check's own access() loop against
the exact build context. The path list comes from the spec at probe
time, so a future spec change is covered automatically; the check itself
still runs only inside the real image build, where `dist/` exists.
## Verification
- `docker buildx build -f .github/docker-context-checks.Dockerfile .`
without the `.dockerignore` exception: fails with the exact production
ENOENT (`src/contracts/native-execution.test.ts`).
- Same command with the exception: passes end to end (all probe stages,
including the drift checks from #12855).
- Static re-sweep of the remaining image-build chain steps
(`build:binary`, replay goldens, semantic-action catalog) against the
ignore rules: their inputs are all in the context; cargo needs no
`tests` directories (no crate declares an explicit `[[test]]` target).
## Risks
- Low. The exception re-adds source test files to the build context
only; image contents do not change (tests are neither compiled into the
production output nor run in the image build — the check only requires
that the referenced files exist).
- The probe addition is one dependency-free Node one-liner.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
Claude Fable 5 (Anthropic, model id `claude-fable-5`), extended
thinking, agentic tool use in Claude Code: GitHub Actions log forensics,
spec-driven path inventory, and local docker buildx verification in both
failing and fixed states.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass (the probe in both
failing-before and passing-after states)
- [x] I have added or updated tests where applicable (the spec-driven
probe walk is the regression test)
- [x] I have updated relevant documentation to reflect my changes
(inline comments explain the invariant)
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - GitHub Actions builds the Docker images that ship Paperclip, and
downstream deployments consume the `-cloud` image variant on every
master merge.
> - PR #12769 slimmed the Docker build context with a broad
`.dockerignore` block for `packages/paperclip-runner`, and the block
also removed three files the image build itself reads.
> - The image build re-runs the runner's generated-file drift checks, so
it found no committed capability contract in the context and failed on
every master commit after the merge.
> - PR CI never runs those checks against the Docker context, so the
pull request stayed green and the breakage only appeared post-merge, on
every image build.
> - This pull request restores the three files with narrow
`.dockerignore` exceptions and adds a PR CI job that runs the drift
checks against the exact Docker build context.
> - The benefit is that image publishing works again now, and the next
context-slimming regression fails the pull request instead of every
post-merge image build.
## Linked Issues or Issue Description
Refs #12769 (the context-slimming change that exposed this) and #12608
(which committed the generated contract outputs the image build checks).
**What happened?**
Every `Docker` workflow run on master failed from 2026-09-04 12:58Z
onward, in both the `build-and-push` and `build-and-push-cloud` jobs.
The failing step reported `Generated contract drift:
generated/capability/capability-contract.md` from
`check:capability-contract` inside `pnpm --filter @paperclipai/server
build`. The committed contract file is current — regeneration on a full
checkout is a no-op. The file was simply absent from the build context:
the new `packages/paperclip-runner/**/*.md` ignore rule strips the
committed drift-check outputs
(`generated/capability/capability-contract.md`,
`generated/capability/downstream-handoff.md`), and the
`packages/paperclip-runner/docs` rule also strips
`docs/capability-contract.md`, which `check:capability-inventory` reads
next in the chain. No cloud image published for eight hours, which
stalled every downstream deployment that consumes the canary images.
**Expected behavior**
The Docker build context must contain every file the image build reads,
and a change that removes one must fail the pull request that introduces
it, not every image build after the merge.
**Steps to reproduce**
1. Check out master at any commit from `af3023f1` onward.
2. Run `docker buildx build -f .github/docker-context-checks.Dockerfile
.` (the probe added by this PR), or start the real `Docker` workflow
build.
3. Observe `Generated contract drift:
generated/capability/capability-contract.md` — while `node
packages/paperclip-runner/scripts/generate-capability-contract.mjs
--check` passes on the same checkout outside Docker.
**Paperclip version or commit**
`d593463ab` (master tip at diagnosis time; first failing commit
`af3023f1`).
**Deployment mode**
GitHub Actions image builds (`docker.yml`), consumed by managed cloud
deployments.
## What Changed
- `.dockerignore`: narrow exceptions (last match wins) re-include the
committed drift-check outputs
(`!packages/paperclip-runner/generated/**`) and the inventory check's
documentation input
(`!packages/paperclip-runner/docs/capability-contract.md`). Every other
exclusion from #12769 stays: no crate declares an explicit `[[test]]`
target, so cargo builds without the `tests` directories, and the image
build chain never runs the excluded smoke scripts.
- `.github/docker-context-checks.Dockerfile` (new): a small probe that
COPYs the real build context — identical `.dockerignore` semantics — and
runs the dependency-independent drift checks inside it
(`generate-capability-contract.mjs --check`,
`check-capability-inventory.mjs`). ajv installs in an isolated directory
for schema validation only; codegen checks such as
`generate-protocol-schema-module` stay out because their emitted bytes
vary with the ajv release and would raise false drift alarms outside the
locked dependency tree.
- `.github/workflows/pr-trusted.yml`: new `docker_context_integrity` job
builds the probe on every full-CI pull request, and the existing
`verify` aggregate now requires its result, so the guard gates merges
through the same required check as the other lanes.
- Activation note: `pr.yml` pins `pr-trusted.yml` by commit SHA, so the
new job starts gating pull requests after the usual follow-up `ci:
activate ...` pin bump once this merges. The `.dockerignore` fix needs
no activation — `docker.yml` reads it directly, so image builds recover
on the first master commit after this merges.
## Verification
- `docker buildx build -f .github/docker-context-checks.Dockerfile .` on
master (before the `.dockerignore` fix): fails with the exact production
error, `Generated contract drift:
generated/capability/capability-contract.md`.
- Same command with the `.dockerignore` exceptions applied: passes,
which also proves BuildKit honors the `!` exceptions, including the file
inside the excluded `docs` directory.
- `node scripts/generate-capability-contract.mjs --check` on a full
checkout: passes both before and after, which confirms the committed
contract was never stale — only missing from the context.
- Static sweep of every script in the image build chain (`build`,
`build:typescript` and their `check:*` steps) against the ignore rules:
the three restored files are the only build inputs the #12769 block
strips.
- YAML for `pr-trusted.yml` lints clean.
## Risks
- Low. The `.dockerignore` exceptions only re-add three committed files
to the build context; image contents do not change otherwise.
- The probe job adds one context transfer and two Node scripts per
full-CI pull request run (about one to two minutes, no dependency
install beyond one isolated ajv package).
- The `verify` aggregate now also requires the new job, mirroring the
existing pattern for the other lanes; on non-full-CI runs the job skips
and `verify` asserts the skip, unchanged from how the other lanes
behave.
- The new job only takes effect for pull requests after a follow-up pin
bump in `pr.yml` (same two-step flow as every `pr-trusted.yml` change).
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
Claude Fable 5 (Anthropic, model id `claude-fable-5`), extended
thinking, agentic tool use in Claude Code: GitHub Actions log forensics
to isolate the failing check, static analysis of the build-chain scripts
against the ignore rules, and local docker buildx runs to reproduce the
failure and verify the fix.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass (the docker probe, both
failing-before and passing-after; the drift checks themselves on a full
checkout)
- [x] I have added or updated tests where applicable (the probe IS the
regression test for this class)
- [x] I have updated relevant documentation to reflect my changes
(inline comments in `.dockerignore` and the probe explain the invariant)
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
Devin Foley