| name | update-stack |
| description | Use this whenever a downstream Node project needs to absorb upstream Devkit Node changes — triggers on "update stack", "sync with devkit", "merge upstream", "pull stack updates", "resolve stack conflicts". Two-phase: ISO merge (stack modules + lib stay byte-identical to upstream) then project alignment (apply MIGRATIONS.md, diff project modules vs `tasks` reference, /verify). Stack-code failures get an issue on `pierreb-devkit/Node`.
|
Update Stack Skill
Two-phase workflow. Phase 1 brings the stack down ISO. Phase 2 aligns the project.
Phase 1 — ISO merge
Goal: stack modules and lib exit this phase identical to upstream. Zero downstream logic in them.
Stack scope = every file under modules/, lib/, config/ (defaults, templates, assets) that exists in devkit-node/master. Auto-discovered by the step 3ter gate; do not enumerate by hand.
1. Setup remote + merge
git remote get-url devkit-node >/dev/null 2>&1 || git remote add devkit-node https://github.com/pierreb-devkit/Node.git
git fetch devkit-node
git merge devkit-node/master
2. Resolve conflicts
| File | Rule |
|---|
Stack module (modules/home|auth|users|tasks|uploads|billing) | git checkout --theirs <file> |
lib/<existing-file> | git checkout --theirs <file> (existing stack framework files — always ISO) |
config/defaults/development.js, production.js, etc. | git checkout --theirs <file> (stack-owned defaults) |
package-lock.json | git checkout --theirs package-lock.json — regenerate after package.json is resolved |
ERRORS.md | Merge stack entries + project entries — never drop lines |
MIGRATIONS.md (if present) | Read it (needed for Phase 2), then git checkout --theirs MIGRATIONS.md |
package.json | git checkout --ours package.json then merge upstream version bumps |
| Downstream-only new files (new modules, helpers, lib additions, scripts) | Never delete — these do not exist in the stack, git checkout --ours <file> if flagged |
After resolving package.json:
npm install --package-lock-only
git add package-lock.json
Stage all resolved files and complete the merge:
git add -u
git merge --continue
3. /verify
Failures typically indicate regressions from conflict resolution — fix these before Phase 2. However, if failures originate from stack module code itself (see 3bis), report them upstream.
3bis. Report stack issues
If /verify failures originate from a stack file (any file under modules/, lib/, or config/ present in devkit-node/master) and not from conflict resolution mistakes, open a GitHub issue on pierreb-devkit/Node.
How to determine the failure origin:
- Stack code failure: error occurs in unmodified stack module files (resolved with
--theirs)
- Conflict resolution mistake: error occurs in files you manually merged or in downstream-only modules
Create the issue:
gh issue create \
--repo pierreb-devkit/Node \
--title "fix(scope): <short description>" \
--body "$(cat <<'BODY'
## Problem
<failing command output>
## Affected file(s)
<list>
## Steps to reproduce
<steps>
BODY
)" \
--label "Fix"
Proceed to Phase 2 and track the upstream fix separately — do not block downstream alignment on it.
3ter. Block on drift
After /verify passes, run a final diff sweep before starting Phase 2. Any shared non-test stack file that diverges from upstream blocks the flow. No ledger exception (user decision 2026-06-02 — drift must never happen, not be documented).
git fetch devkit-node master --quiet
drift_found=0
while IFS= read -r f; do
if git cat-file -e "devkit-node/master:$f" 2>/dev/null && git cat-file -e "HEAD:$f" 2>/dev/null; then
echo "BLOCK: drift on shared file: $f"
echo " Fix A — revert to upstream: git checkout devkit-node/master -- $f"
echo " Fix B — promote upstream: open a devkit PR with the change, merge, /update-stack here"
echo " Fix C — relocate: move logic to a downstream-only module or config/defaults/<project>.config.js"
drift_found=1
elif git cat-file -e "devkit-node/master:$f" 2>/dev/null; then
echo "BLOCK: missing locally (was on upstream): $f"
echo " Fix — restore: git checkout devkit-node/master -- $f"
drift_found=1
fi
done < <(git diff --name-only devkit-node/master HEAD -- modules lib config 2>/dev/null \
| grep -vE "/(tests|__tests__)/" | grep -vE "\.(test|spec)\.(js|jsx|ts|tsx)$")
[ "$drift_found" -eq 1 ] && exit 1
echo "3ter: no drift — OK"
Rules:
- Block on ANY shared-file divergence. No "declare and skip" path — the
DOWNSTREAM_PATCHES.md ledger model was abandoned 2026-06-02 (memory feedback_no_dev_in_shared_modules).
- Scan source is
git diff --name-only devkit-node/master HEAD (bidirectional) — catches both files that differ AND files present upstream but missing locally (deleted downstream). The previous git ls-files approach only saw locally-present files.
- Test files (paths containing
/tests/ or /__tests__/, or filenames ending .test.{js,jsx,ts,tsx} / .spec.{js,jsx,ts,tsx}) are excluded — downstream test adaptations are acceptable.
- This gate runs after
/verify (never blocks on transient verify failures) and before Phase 2 (failure is recoverable — no merge commit yet).
Phase 2 — Project alignment
Goal: project-specific modules work and match stack patterns.
4. Apply MIGRATIONS.md (if present)
Read the last entries — they list breaking changes requiring updates in project modules. Apply each one to non-stack modules.
5. Align project modules
Diff project modules against modules/tasks (stack reference). Fix any pattern drift flagged by ERRORS.md.
6. /verify
