Merge pull request #3177 from pierreb-devkit/chore/rework-update-stack-skill

chore(update-stack): rework skill as 2-phase ISO merge, remove stack-maintainer agent

Author: PierreBrisorgueil

.claude/agents/stack-maintainer.md

@@ -5,60 +5,65 @@ description: Merge the latest changes from the Devkit Node stack repository into
 
 # Update Stack Skill
 
-Pure git workflow for merging stack updates while preserving downstream customizations.
+Two-phase workflow. Phase 1 brings the stack down ISO. Phase 2 aligns the project.
 
-## Steps
+## Phase 1 — ISO merge
 
-### 1. Add the stack remote (if not already added)
+**Goal: stack modules and lib exit this phase identical to upstream. Zero downstream logic in them.**
+
+Stack modules: `home`, `auth`, `users`, `tasks`, `uploads` — Stack core: `lib/` (existing files), `config/defaults/` (stack-owned files only)
+
+### 1. Setup remote + merge
 
 ```bash
-git remote add devkit-node https://github.com/pierreb-devkit/Node.git
+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. Fetch the latest stack changes
+### 2. Resolve conflicts
+
+| File | Rule |
+|------|------|
+| Stack module (`modules/home\|auth\|users\|tasks\|uploads`) | `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 |
+| `MIGRATION.md` (if present) | Read it (needed for Phase 2), then `git checkout --theirs MIGRATION.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`:
 
 ```bash
-git fetch devkit-node
+npm install --package-lock-only
+git add package-lock.json
 ```
 
-### 3. Merge the stack updates
+Stage all resolved files and complete the merge:
 
 ```bash
-git merge devkit-node/master
+git add -u
+git merge --continue
 ```
 
-### 4. Handle conflicts
+### 3. `/verify`
 
-Focus on these high-conflict areas:
+All failures here are regressions from conflict resolution. Fix before Phase 2.
 
-- `config/defaults/` — Merge stack defaults carefully, preserve downstream overrides
-- `lib/services/` — Accept stack changes unless downstream has specific customizations
-- `package.json` — Keep downstream dependencies, accept stack dependency updates
-- `modules/*/` — Stack only ships `tasks`, `home`, `auth`, `users`, `uploads` — downstream modules are safe
+---
 
-### 5. Verify after merge
+## Phase 2 — Project alignment
 
-```bash
-npm run lint
-npm test
-```
+**Goal: project-specific modules work and match stack patterns.**
+
+### 4. Apply MIGRATION.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`.
 
-## Conflict Strategy
-
-| File/Dir               | Strategy                                      |
-| ---------------------- | --------------------------------------------- |
-| `config/defaults/`     | Preserve downstream values, take stack structure |
-| `lib/`                 | Prefer stack (core framework code)            |
-| `modules/tasks/`       | Prefer stack (reference module)               |
-| `modules/home/`        | Prefer stack (core module)                    |
-| `modules/auth/`        | Prefer stack (security — take updates)        |
-| `modules/users/`       | Prefer stack unless customized                |
-| `modules/uploads/`     | Prefer stack unless customized                |
-| Custom modules         | Always keep downstream                        |
-| `package.json`         | Merge carefully, keep both dependency sets    |
-
-## Notes
-
-- Stack modules (`tasks`, `home`, `auth`, `users`, `uploads`) are reference implementations — downstream may customize them
-- Custom modules added downstream will never conflict
-- After merge, check `config/defaults/development.js` to ensure new stack config keys are present
+### 6. `/verify`

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

@@ -9,9 +9,10 @@ Run lint → tests and report results.
 
 ## Steps
 
-1. Run `npm run lint` to check code quality (read-only, no auto-fix)
-2. Run `npm test` to run all tests
-3. Summarize results:
+1. Read `ERRORS.md` — scan changed files for any pattern listed as wrong. Flag violations before running tooling.
+2. Run `npm run lint` to check code quality (read-only, no auto-fix)
+3. Run `npm test` to run all tests
+4. Summarize results:
    - ✅ All checks passed → ready to commit
    - ❌ Some checks failed → show what failed and suggest next action
 

.claude/skills/verify/SKILL.md

@@ -8,7 +8,7 @@ It is designed to be cloned into downstream projects and kept up-to-date through
 
 Source of truth: `README.md` + `package.json` scripts.
 
-The `.claude/` folder contains embedded settings, skills, and agents that are available immediately after cloning.
+The `.claude/` folder contains embedded settings and skills that are available immediately after cloning.
 
 ## Canonical commands
 
@@ -52,10 +52,6 @@ Use `.claude/skills/*/SKILL.md` as the primary workflow source for Claude.
 | `/naming`        | Apply or audit naming conventions                     |
 | `/pull-request`  | Full PR lifecycle: draft, CI, monitor loop, iterate   |
 
-## Embedded agent
-
-- `stack-maintainer` (`.claude/agents/stack-maintainer.md`): quick review guard for mergeability, security, and modularity.
-
 ## Stack merge workflow
 
 See README — stack merge workflow section.