Skip to content

Commit 7be1220

Browse files
feat(skills/update-stack): drop ledger condition + auto-derive scan list (#4232)
* feat(skills/update-stack): drop ledger condition + auto-derive scan list (#4231) Three coupled changes to step 3ter drift gate: 1. Drop `DOWNSTREAM_PATCHES.md` ledger exception — block on ANY shared non-test file divergence vs `devkit-vue/master`. User decision 2026-06-02 (memory `feedback_no_dev_in_shared_modules`). Resolution path becomes revert / promote-up / relocate. 2. Replace hardcoded module list (`src/modules/home auth users tasks core app secure`) with `src/modules src/lib src/config`. Old enum silently missed `src/modules/admin`, `app`, `billing`, `core`, `legal`, `organizations` AND included a non-existent `src/modules/secure`. Re-audit on trawl_vue with corrected scan surfaced 13 undeclared drifts (~700 LOC). 3. Drop stale `src/modules/secure` entry — never existed on devkit Vue origin/master. Operational note: `src/modules/app/app.router.js` historically diverges on every downstream (downstream routes). Under no-ledger it MUST be refactored to keep `app.router.js` stack-iso. Until then the gate will block every Vue downstream `/update-stack` — forcing function as intended. Mirrors infra#37 (PRF Phase 0.5 gate) for `/update-stack`-time enforcement. * docs(skills/update-stack): address Copilot + critical-review (#4232) - Rewrite Phase 1 'Stack modules' line + 3bis 'stack code' line to point at auto-discovery (no hardcoded enumeration). - Tighten test-files exclusion description to match the actual regex. - Add Rules bullet noting e2e helpers under src/lib/helpers/e2e/ are scanned (stack-managed). Surfaced by critical-review fallback. - Refine app.router.js Rules text: clarify that the extension hook needed for downstream route registration does NOT currently exist; the refactor must add it. Surfaced by Copilot review. Separate follow-up issue will be filed for switching the scan source from downstream `git ls-files` to upstream `git ls-tree` — closes the coverage gap for stack files missing on downstream (Copilot review finding, out of scope for this PR).
1 parent 0560aab commit 7be1220

1 file changed

Lines changed: 16 additions & 16 deletions

File tree

.claude/skills/update-stack/SKILL.md

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Two-phase workflow. Phase 1 brings the stack down ISO. Phase 2 aligns the projec
1717

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

20-
Stack modules: `home`, `auth`, `users`, `tasks`, `core`, `app`, `secure`
20+
Stack scope = every file under `src/modules/`, `src/lib/`, `src/config/` that exists in `devkit-vue/master`. Auto-discovered by the step 3ter gate; do not enumerate by hand.
2121

2222
### 1. Setup remote + merge
2323

@@ -64,7 +64,7 @@ Failures typically indicate regressions from conflict resolution — fix these b
6464

6565
### 3bis. Report stack issues
6666

67-
If `/verify` failures originate from **stack module code** (`home`, `auth`, `users`, `tasks`, `core`, `app`, `secure`) and not from conflict resolution mistakes, open a GitHub issue on `pierreb-devkit/Vue`.
67+
If `/verify` failures originate from a **stack file** (any file under `src/modules/`, `src/lib/`, or `src/config/` present in `devkit-vue/master`) and not from conflict resolution mistakes, open a GitHub issue on `pierreb-devkit/Vue`.
6868

6969
**How to determine the failure origin:**
7070
- **Stack code failure:** error occurs in unmodified stack module files (resolved with `--theirs`)
@@ -92,9 +92,9 @@ BODY
9292

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

95-
### 3ter. Block on undeclared drift
95+
### 3ter. Block on drift
9696

97-
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.
97+
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).
9898

9999
```bash
100100
git fetch devkit-vue master --quiet
@@ -105,25 +105,25 @@ while IFS= read -r f; do
105105
[ -z "$upstream_blob" ] && continue # downstream-only file — skip
106106
local_blob=$(git rev-parse "HEAD:$f" 2>/dev/null)
107107
if [ "$upstream_blob" != "$local_blob" ]; then
108-
if ! grep -qF "'$f'" DOWNSTREAM_PATCHES.md 2>/dev/null; then
109-
echo "BLOCK: undeclared drift on stack file: $f"
110-
echo " Fix A — revert to upstream: git checkout devkit-vue/master -- $f"
111-
echo " Fix B — declare it: add '$f' + rationale to DOWNSTREAM_PATCHES.md"
112-
drift_found=1
113-
fi
108+
echo "BLOCK: drift on shared stack file: $f"
109+
echo " Fix A — revert to upstream: git checkout devkit-vue/master -- $f"
110+
echo " Fix B — promote upstream: open a devkit PR with the change, merge, /update-stack here"
111+
echo " Fix C — relocate: move logic to a downstream-only module or src/config/defaults/<project>.config.js"
112+
drift_found=1
114113
fi
115-
done < <(git ls-files src/modules/home src/modules/auth src/modules/users src/modules/tasks src/modules/core src/modules/app src/modules/secure 2>/dev/null \
114+
done < <(git ls-files src/modules src/lib src/config 2>/dev/null \
116115
| grep -vE "/(tests|__tests__)/" | grep -vE "\.(test|spec)\.(js|jsx|ts|tsx|vue)$")
117116

118117
[ "$drift_found" -eq 1 ] && exit 1
119-
echo "3ter: no undeclared drift — OK"
118+
echo "3ter: no drift — OK"
120119
```
121120

122121
**Rules:**
123-
- Missing `DOWNSTREAM_PATCHES.md` = no declared divergences allowed (treat as empty).
124-
- Declare diverging paths in `DOWNSTREAM_PATCHES.md` as `'path/to/file'` (single-quoted) — the gate matches on the quoted token to avoid substring collisions.
125-
- Downstream-only files (new modules, composables) are not scanned — the sweep only covers the stack module directories listed above.
126-
- `src/modules/app/app.router.js` legitimately diverges (downstream routes) — declare it in `DOWNSTREAM_PATCHES.md` once on project bootstrap.
122+
- 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`).
123+
- Scan covers the full stack tree (`src/modules`, `src/lib`, `src/config`) — auto-discovers every shared module. Per-file `git ls-tree` on upstream filters downstream-only files.
124+
- Test files (paths containing `/tests/` or `/__tests__/`, or filenames ending `.test.{js,jsx,ts,tsx,vue}` / `.spec.{js,jsx,ts,tsx,vue}`) are excluded — downstream test adaptations are acceptable.
125+
- E2E helpers under `src/lib/helpers/e2e/` ARE scanned — they are stack-managed. Downstream modification triggers BLOCK; use Fix B (promote upstream) if a downstream needs e2e helper changes.
126+
- `src/modules/app/app.router.js` historically diverged on every downstream (downstream routes). Under no-ledger this must be refactored: `app.router.js` does NOT currently expose an extension hook — the refactor needs to add one (e.g. a `registerDownstreamRoutes()` call sourced from a downstream-only module like `src/modules/{project}/{project}.router.js`), then keep `app.router.js` stack-iso. Until that refactor lands, this gate will BLOCK on every Vue downstream `/update-stack`.
127127
- This gate runs **after** `/verify` (never blocks on transient verify failures) and **before** Phase 2 (failure is recoverable — no merge commit yet).
128128
- Ref: plan `2026-05-30-trawl-devkit-perfect-alignment.md` Tasks E.1 + E.2.
129129

0 commit comments

Comments
 (0)