feat(skills/update-stack): block on undeclared drift vs upstream#3760
Conversation
Add gate 3ter to Phase 1: after /verify passes, diff each stack-module non-test file against devkit-node/master. Any file that diverges AND is not declared in DOWNSTREAM_PATCHES.md causes exit 1 with a clear fix message. Missing ledger = no declared divergences allowed. Prevents trawl-style silent drift (3 arch violations + 9 promote-up candidates found 2026-05-30 after weeks of unchecked accumulation). Closes #3759 — plan 2026-05-30-trawl-devkit-perfect-alignment.md (E.2)
|
Warning Review limit reached
More reviews will be available in 54 minutes and 44 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughThis PR adds documentation for a new Phase 1 verification gate that blocks Phase 2 execution if any stack file differs from upstream without being declared in ChangesUndeclared Drift Gate Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related issues
Possibly related PRs
Suggested labels
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
Adds a new “3ter” gate to the /update-stack skill documentation to block Phase 2 when stack-managed files drift from devkit-node/master without being declared in DOWNSTREAM_PATCHES.md, strengthening enforcement of ISO alignment before project-specific work begins.
Changes:
- Introduces “3ter. Block on undeclared drift” (post-
/verify, pre-Phase 2) with a bash sweep that checks stack paths for upstream divergence. - Defines operational rules around missing
DOWNSTREAM_PATCHES.mdand auto-skipping downstream-only project config files.
…gate - Replace `git hash-object "$f"` with `git rev-parse HEAD:"$f"` — compares committed blobs rather than working-tree bytes (CRLF-safe, no false drift from uncommitted changes post-merge) - Replace `grep -qF "$f"` with `grep -qF "'$f'"` — matches the single-quoted token in DOWNSTREAM_PATCHES.md to prevent substring false-positives - Reword rules: remove misleading note about config/defaults auto-skip (those paths are simply not in the scanned directories), clarify that downstream-only files are never scanned Per Copilot review on #3760
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/skills/update-stack/SKILL.md:
- Around line 111-112: The gate currently lists "modules/billing" in the git
ls-files filter but the declared stack module set in SKILL.md only includes
"home/auth/users/tasks/uploads" (references to the stack module declarations
around the top and the module list). Either remove "modules/billing" from the
done < <(git ls-files ...) command or add "billing" to the declared stack
modules list so the gate and the module declarations match; update the module
list in the doc to include "billing" if that module should be stack-managed, or
remove it from the gate if it should be excluded.
- Line 112: The current grep pipeline line that excludes test files ("| grep -v
\"/tests/\" | grep -vE \"\\.(test|spec)\\.js$\"") is too narrow; update it to
also exclude common test directories like "__tests__" and common test file
extensions (.test/.spec with js, jsx, ts, tsx). Replace the two filters with
broader exclusions that drop "/tests/" and "/__tests__/" and use a single
extended regex to filter "\.(test|spec)\.(js|jsx|ts|tsx)$" so files like
"foo.test.tsx" and directories "__tests__" are ignored.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: a5636a60-c6f8-4dca-b33c-b9818efab3c2
📒 Files selected for processing (1)
.claude/skills/update-stack/SKILL.md
…test exclusion - Add `billing` to stack module declaration (it exists in devkit/Node: modules/billing/) — gate and header were inconsistent - Update conflict resolution table accordingly - Broaden test-file exclusion: add /__tests__/ directory pattern and extend extensions to (js|jsx|ts|tsx) for consistency Per CodeRabbit review on #3760
Summary
/update-stack(after/verifypasses, before Phase 2): diffs each stack-module non-test file againstdevkit-node/master; any divergence not declared inDOWNSTREAM_PATCHES.mdcausesexit 1with a clear fix messageDOWNSTREAM_PATCHES.md= no declared divergences allowed (treated as empty)config/defaults/<project>.config.jsis auto-skipped (absent from devkit →upstream_blobempty)Why
A 2026-05-30 audit of
comes-io/trawl_nodefound 3 architectural violations + 9 promote-up candidates in stack-managed modules (auth,users,billing,lib). These accumulated silently over weeks because/update-stackhad no gate — ISO merge could pass with--theirsresolving conflicts while downstream-committed changes in shared modules sailed through undetected.This gate enforces the "no dev in shared modules" rule at the only moment it can be enforced mechanically: when the downstream actually runs
/update-stack.Gate test output (fake-drift exercise on trawl_node)
Block path (undeclared drift —
exit 1):Pass path (all diverging files declared in ledger —
exit 0):Note: the 3 real blocking files (
lib/helpers/guides.js,lib/services/express.js,modules/tasks/doc/tasks.yml) are genuine pre-existing drift intrawl_node— Task E.1 (ledger bootstrap) will resolve them by declaring or reverting each one.Complement
DOWNSTREAM_PATCHES.mdledger convention (downstreams must create ledger before first/update-stackwith this gate)feedback_no_dev_in_shared_modulesCloses #3759 — plan
2026-05-30-trawl-devkit-perfect-alignment.mdTask E.2Summary by CodeRabbit