@webpieces/rules-config 0.3.222 → 0.3.224

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/rules-config",
-  "version": "0.3.222",
+  "version": "0.3.224",
   "description": "Shared webpieces.config.json loader. Single source of truth for validation rule configuration consumed by @webpieces/ai-hook-rules, @webpieces/code-rules, and @webpieces/nx-webpieces-rules.",
   "type": "commonjs",
   "main": "./src/index.js",

package/templates/webpieces.git-workflow.md

@@ -0,0 +1,94 @@
+# webpieces Git & PR Workflow (for the AI)
+
+Generated by `@webpieces/pr-gate` (refreshed on every `wp-*` PR/merge command, so it can't drift).
+Read this before running any `wp-git-update` / `wp-start-upsert-pr` / `wp-finish-upsert-pr`.
+
+## Golden rule: the tooling NEVER commits your work for you
+
+Before running any `wp-*` PR/merge command, your working tree must be 100% clean:
+
+- **Commit** every changed tracked file.
+- **Add + commit, or delete** every untracked file.
+
+Each command runs `git status --porcelain` first and **aborts** if anything is uncommitted — including
+**untracked** files (gitignored paths like `.webpieces/` are excluded). The tooling deliberately does
+**not** `git add -A` your tree: a blanket sweep once committed a stale untracked directory into a
+squash commit. If a command tells you the tree is dirty, commit or delete the listed files, then re-run.
+
+## The 3-point fork-point system
+
+- **A = fork point**: `git merge-base origin/main HEAD`
+- **B = feature HEAD**: your branch tip
+- **C = main HEAD**: `origin/main`
+
+Never `git merge` or `git rebase` main into your branch directly — it breaks the fork point (A) that
+produces clean PR diffs. Sync only via `pnpm wp-git-update` (a 3-point squash-update). This is enforced
+by the `redirect-how-to-merge-main` guard.
+
+## Commands
+
+1. **`pnpm wp-git-update`** — squash-update your branch from main. Clean merge → finalizes. Conflicts →
+   writes `.webpieces/instruct-ai/webpieces.mergeprocess.md` and hands resolution to you; finish with
+   `pnpm wp-finish-upsert-pr`.
+2. **`pnpm wp-start-upsert-pr`** — update from main, push, run an advisory build gate, then tells you to
+   write `review.json`. Never creates the PR itself.
+3. **`pnpm wp-finish-upsert-pr`** — validates any in-progress merge, requires your `review.json`, runs
+   the **authoritative** build gate, pushes, and creates/updates the PR.
+
+## Two possible outcomes of a squash-update
+
+A `wp-git-update` (the squash step inside `wp-start-upsert-pr` too) ends one of two ways. The tool
+`git merge --squash`es your feature onto a fresh copy of main; whether that merges cleanly decides
+who does the work.
+
+### Outcome A — CLEAN merge (the tool does everything; you do nothing)
+
+```
+you: pnpm wp-git-update
+  tool: assertCleanTree            # you must have committed your own work first
+  tool: backup branch; checkout main; pull; create <feature>Squash off main
+  tool: git merge --squash <feature>          # SUCCEEDS — stages the combined result
+  tool: git commit -m "Squash merge of <feature>"     # <-- the TOOL commits (mechanical)
+  tool: delete old branch; force-push to the stable base; rename to next generation
+  done — no AI/human merge work.
+```
+
+There is **no `git add` here** — `git merge --squash` staged only the merge result, and the tool
+commits exactly that. The commit is a pure function of your already-committed work + main.
+
+### Outcome B — CONFLICT merge (the AI resolves; the tool still commits)
+
+```
+you: pnpm wp-git-update
+  tool: assertCleanTree; backup; checkout main; pull; create <feature>Squash
+  tool: git merge --squash <feature>          # CONFLICTS — conflicted files left with markers
+  tool: writes .webpieces/merge-info/<feature>/ (A=fork / B=feature / C=main context + diffs)
+  tool: writes .webpieces/instruct-ai/webpieces.mergeprocess.md, then exits (code 2)
+  ---- hand-off to the AI ----
+  AI:  read webpieces.mergeprocess.md
+  AI:  per conflicted file -> resolve markers -> git add <file> -> write merge-explanation.md
+  AI:  pnpm wp-finish-upsert-pr
+  tool: validateResolution (no markers left, every file has an explanation)
+  tool: assertNoUntracked -> git add -u -> git commit "... (conflicts resolved)"   # <-- TOOL commits
+  tool: build gate -> push -> create/update PR
+```
+
+Who does what on the conflict path:
+- **You/the AI** supply the *judgment*: how to combine the conflicting changes. You edit the files,
+  `git add` them, and write each `merge-explanation.md`.
+- **The tool** still makes the *commit*. You are BLOCKED from `git commit` / `git push` / `gh pr`
+  while the merge is in progress (the `merge-in-progress-guard`); `wp-finish-upsert-pr` is what
+  validates and commits. `git add -u` stages only your tracked resolutions and **refuses** if any
+  untracked file is present — commit or delete those first, the tool will not sweep them in.
+
+The two docs cooperate: **this file** is the always-present overview of both paths;
+**`webpieces.mergeprocess.md`** is written *only when there is a conflict* and lists the exact files
+to resolve for that specific merge.
+
+## Before you trust a push
+
+The build gate validates the **working tree**; the push sends **HEAD**. A green build on disk does
+**not** mean the committed tree is correct. After any fix, run `git show --stat HEAD` (or `git status`)
+and confirm the commit actually contains your fix. The clean-tree guard enforces `working tree == HEAD`
+before the build gate and push, so a fix left uncommitted will block the PR instead of silently pushing
+a stale commit.