Skip to content

feat(skills/update-stack): drop ledger condition + auto-derive scan list #3778

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PierreBrisorgueil merged 2 commits into from
Jun 3, 2026
+14 −15
Merged

feat(skills/update-stack): drop ledger condition + auto-derive scan list #3778

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
33ee527
feat(skills/update-stack): drop ledger condition + auto-derive scan l…
PierreBrisorgueil Jun 3, 2026
b3041ce
docs(skills/update-stack): address Copilot review (#3778)
PierreBrisorgueil Jun 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 14 additions & 15 deletions .claude/skills/update-stack/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Two-phase workflow. Phase 1 brings the stack down ISO. Phase 2 aligns the projec

**Goal: stack modules and lib exit this phase identical to upstream. Zero downstream logic in them.**

Stack modules: `home`, `auth`, `users`, `tasks`, `uploads`, `billing` — Stack core: `lib/` (existing files), `config/defaults/` (stack-owned files only)
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

Expand Down Expand Up @@ -60,7 +60,7 @@ Failures typically indicate regressions from conflict resolution — fix these b

### 3bis. Report stack issues

If `/verify` failures originate from **stack module code** (`home`, `auth`, `users`, `tasks`, `uploads`) or **stack core** (`lib/`, `config/defaults/`) and not from conflict resolution mistakes, open a GitHub issue on `pierreb-devkit/Node`.
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`)
Expand Down Expand Up @@ -88,9 +88,9 @@ BODY

Proceed to Phase 2 and track the upstream fix separately — do not block downstream alignment on it.

### 3ter. Block on undeclared drift
### 3ter. Block on drift

After `/verify` passes, run a final diff sweep before starting Phase 2. Any stack file that diverges from upstream **and** is not declared in `DOWNSTREAM_PATCHES.md` blocks the flow.
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).

```bash
git fetch devkit-node master --quiet
Expand All @@ -101,24 +101,23 @@ while IFS= read -r f; do
[ -z "$upstream_blob" ] && continue # downstream-only file — skip
local_blob=$(git rev-parse "HEAD:$f" 2>/dev/null)
if [ "$upstream_blob" != "$local_blob" ]; then
if ! grep -qF "'$f'" DOWNSTREAM_PATCHES.md 2>/dev/null; then
echo "BLOCK: undeclared drift on stack file: $f"
echo " Fix A — revert to upstream: git checkout devkit-node/master -- $f"
echo " Fix B — declare it: add '$f' + rationale to DOWNSTREAM_PATCHES.md"
drift_found=1
fi
echo "BLOCK: drift on shared stack 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
fi
done < <(git ls-files modules/home modules/auth modules/users modules/tasks modules/uploads modules/billing lib config/defaults 2>/dev/null \
done < <(git ls-files modules lib config 2>/dev/null \
| grep -vE "/(tests|__tests__)/" | grep -vE "\.(test|spec)\.(js|jsx|ts|tsx)$")
Comment on lines +110 to 111

[ "$drift_found" -eq 1 ] && exit 1
echo "3ter: no undeclared drift — OK"
echo "3ter: no drift — OK"
```

**Rules:**
- Missing `DOWNSTREAM_PATCHES.md` = no declared divergences allowed (treat as empty).
- Declare diverging paths in `DOWNSTREAM_PATCHES.md` as `'path/to/file'` (single-quoted) — the gate matches on the quoted token to avoid substring collisions.
- Downstream-only files (new modules, helpers, lib additions) are not scanned — the sweep only covers the stack directories listed above.
- 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 covers the full stack tree (`modules`, `lib`, `config`) — auto-discovers every shared module. Per-file `git ls-tree` on upstream filters downstream-only 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).
- Ref: plan `2026-05-30-trawl-devkit-perfect-alignment.md` Tasks E.1 + E.2.

Expand Down