docs(spike): groundgate routine-vs-grounded boundary audit (#388) - #393
Merged
Conversation
dngioidev
force-pushed
the
docs/388-groundgate-boundary-spike
branch
from
August 6, 2026 16:30
999d574 to
be11116
Compare
Audits 5 real autopilot/delivery forks against the "which approach is routine" rule (spec sec7): finds one real gap (#307's uncited, self-admitted unconfirmed external-system assumption) and four cases where the current boundary already works fine. Proposes two narrow categories move to a lightweight inline comparison instead of a full spike — new-dependency picks and self-admitted unverified correctness assumptions — leaving everything else routine. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SATRHKa6mDHDuirhP6QuwL
dngioidev
force-pushed
the
docs/388-groundgate-boundary-spike
branch
from
August 7, 2026 02:24
be11116 to
9fe0eb0
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #388
Summary
Spike findings doc:
docs/spikes/2026-08-06-groundgate-boundary.md. No code changes — deliverable is research + a proposed rule change.Audited 5 real forks from recent deliveries against spec sec7's "which approach... routine" rule: #307 (agy relative-path emission), #378 (session-window self-pause), #379 (delivery-subagent model pin), #386 (doctor graph-availability heuristic), and ADR-0008 (cockpit re-architecture). One real gap found: #307's fix shipped a correctness-critical assumption about agy's MCP subprocess CWD that the PR itself called "not independently confirmed" — no citation, no comparison, no pause, just a self-authored caveat and a documented fallback. The other four show the current boundary working as intended: #378 correctly escalated because it touched a signed ADR (ADR-0003); #379 was informally grounded via #101 precedent; #386's heuristic pick was low-stakes, single-file, and reasoned inline; ADR-0008's architecture-scale fork got a proper spike + owner sign-off, with smaller library picks (FastAPI, pywinpty) correctly left routine on the spike's own findings.
Recommendation: move two narrow categories from "routine, no citation" to "lightweight inline comparison" (not a full spike ticket/branch/PR) — (1) self-admitted unverified correctness assumptions about external systems, formalized as a mandatory PR-body heading rather than today's optional honesty convention, and (2) new-dependency introductions, via a one-line "why this, not the obvious alternative" note hooked to the existing
depguard.mjsgate. Everything else — UI variants, precedent-backed tool/model choices, single-file reversible implementation heuristics, and forks big enough to be flagged as spike-worthy up front — stays exactly as routine as it is today; the audit found no case for tightening those.Open question left for the owner
Whether the "unverified assumption" requirement should be gate-enforced (a mechanical PR-body scan for hedge language without a paired citation/follow-up) or left as a
forge:reviewerrole-card instruction. Not resolved in the doc — flagged for the owner to pick before this becomes a plan.Test plan
node plugin/scripts/gates/docsync.mjs— clean (62 docs indexed).docs/README.md§ Spikes.🤖 Generated with Claude Code