Skip to content

fix(check-scope): exempt .agents/research/ as a RAD process artifact - #104

Merged
seanrreid merged 1 commit into
mainfrom
fix/scope-exempt-research-artifacts
Aug 10, 2026
Merged

fix(check-scope): exempt .agents/research/ as a RAD process artifact#104
seanrreid merged 1 commit into
mainfrom
fix/scope-exempt-research-artifacts

Conversation

@seanrreid

Copy link
Copy Markdown
Owner

One-line fix plus a regression case: .agents/research/ is now exempt in
check-scope.sh's ALWAYS_ALLOW_PREFIXES, alongside .agents/logs/,
.agents/plans/, and .agents/state/.

The gap

/rad-research commits its artifact to the work branch before the plan exists,
so no plan can ever declare it in Files in Scope. Every other RAD process artifact
was already exempt — #14 covered logs, plans, state, and findings, and missed
research.

The consequence is that a deliver which never touched the artifact fails Gate 2 on
its own branch's first commit.

How it surfaced

Delivering #89 on rad/wave-back-pressure. Every wave passed, 239/239 harness tests
and all 15 shell suites green — then the scope gate failed on exactly one file:

✗ Scope violation: wave-back-pressure

Out-of-scope changes (1):
  ✗ .agents/research/wave-back-pressure.md

That file was committed 2026-08-04 as the branch's first commit, four days
before the plan was written. git log af144b2..HEAD -- .agents/research/ is empty —
no wave touched it. The stalled 2026-08-06 deliver would have hit the same wall.

Why it can't be worked around inside the affected delivery

Adding the path to the plan's Files in Scope would edit an approved plan doc and
invalidate its approval fingerprint:

ok: fingerprint — plan doc matches the approved fingerprint

RAD has no re-approval path (#39), so an amended plan cannot be re-attested. The fix
has to live here, in the checker.

Verification

  • New case AC#3b mirrors AC#3's existing idiom.
  • Proven non-vacuous: with check-scope.sh stashed back to its pre-fix state the
    case fails — ✗ AC#3b: .agents/research/ change should exit 0 (got 1).
  • scripts/test-check-scope.sh → ALL PASS (8 cases).
  • All 14 other scripts/test-*.sh suites → PASS.
  • scripts/lint-shell-safety.sh → exit 0.

Scope

Touches a self-protected path (scripts/check-scope.sh), so this can never be
auto-cleared by severity routing — architect review is the intended path.

This is a direct fix rather than a planned RAD delivery, on the grounds that a
one-line allowlist addition with a regression test is below the threshold where a
plan adds information. That threshold is exactly what #81 (tiered planning,
/rad-plan --light) exists to formalize.

`/rad-research` commits its artifact to the work branch BEFORE the plan
exists, so no plan can ever declare it in Files in Scope. `.agents/research/`
was missing from ALWAYS_ALLOW_PREFIXES while `.agents/logs/`,
`.agents/plans/`, and `.agents/state/` were all exempt — #14 covered the
others and missed this one.

The result is a deliver that never touched the artifact failing Gate 2 on its
own branch's first commit. Observed on rad/wave-back-pressure (#89): the scope
check flagged `.agents/research/wave-back-pressure.md`, committed 2026-08-04
as the branch's first commit, four days before the plan was written.

There is no workaround from inside the affected delivery. Adding the path to
the plan's Files in Scope would edit an approved plan doc and invalidate its
approval fingerprint, and RAD has no re-approval path (#39).

Adds AC#3b, mirroring AC#3's idiom. Verified non-vacuous: without the
one-line exemption the case fails with exit 1.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@seanrreid
seanrreid merged commit 8344f4f into main Aug 10, 2026
7 checks passed
@seanrreid
seanrreid deleted the fix/scope-exempt-research-artifacts branch August 10, 2026 16:59
@seanrreid

Copy link
Copy Markdown
Owner Author

Correction. This PR body states that "RAD has no re-approval path (#39)". That is wrong.

PR #45 closed that gap on 2026-06-23. harness/transitions.js:94-116 blocks a duplicate approved event only when the plan fingerprint is unchanged, and explicitly admits a re-attestation whose fingerprint differs. The wave-back-pressure approval carried a fingerprint (0b874d3b…), so editing the plan and re-running /rad-approve was in fact available.

The routing decision still stands, on better grounds than the ones given: .agents/research/ should be exempt for every delivery, so amending a single plan would have papered over a general defect with a per-plan workaround. The fix belonged here in check-scope.sh.

Log corrected in #106.

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.

1 participant