docs(grokbuild): document clean-baseline worktree workflow

docs/grokbuild/README.md

@@ -21,7 +21,7 @@ Grok Build is treated as a **bounded engineering laboratory**, not an autonomous
 
 ## 2. Initial Setup (One-Time)
 
-1. Clone the repo and checkout `feat/grok43-agent-config` (or main once merged).
+1. Clone the repo and checkout `main`.
 2. Copy `docs/examples/grok43.env.example` to your local `.env` and fill in your `XAI_API_KEY`.
 3. Install Grok Build CLI using the current official xAI instructions.
    Do not pipe installer scripts into a shell unless the source and any available checksum/signature have been verified.
@@ -34,17 +34,66 @@ Grok Build is treated as a **bounded engineering laboratory**, not an autonomous
 
 Every productive session follows this pattern:
 
-### Phase 0: Bootstrap (Mandatory)
+### Phase 0: Bootstrap + Workspace Hygiene (Mandatory)
-- Invoke the `core-bootstrap` skill (or run it manually via the Grok Build interface).
+
+- Invoke `/core-bootstrap` or run the skill manually through Grok Build.
 - Read `GROK.md` + `AGENTS.md` + `docs/runtime_contracts.md`.
-- Run smoke suite.
+- Confirm the current directory and repository root before any operation:
-- Read most recent relevant `HANDOFF-*.md`.
+  ```bash
+  pwd
+  git rev-parse --show-toplevel
+  test -f GROK.md
+  test -f AGENTS.md
+  ```
+- Inspect the local tree before any branch movement:
+  ```bash
+  git status --short --branch
+  git diff --stat
+  git diff --name-status
+  git diff --cached --name-status
+  git stash list
+  git worktree list
+  ```
+- If the tree is dirty, classify every loose file/change before switching branches:
+  - current task work;
+  - likely prior PR/branch work;
+  - accidental generated artifact;
+  - evidence/report file that should be restored;
+  - unknown.
+- For unknown work, inspect history and open PR state before stashing or restoring:
+  ```bash
+  git diff -- <path>
+  git log --oneline --decorate --all -- <path>
+  git branch --sort=-committerdate | head -20
+  gh pr list --state open --limit 20
+  gh pr status
+  ```
+- Preserve unknown work with a descriptive stash; never destroy it blindly:
+  ```bash
+  git stash push -m "WIP unknown before <task-slug>: <short file summary>" -- <paths>
+  ```
+- Establish a clean, current baseline:
+  ```bash
+  git fetch origin --prune
+  git switch main
+  git pull --ff-only origin main
+  git status --short --branch
+  ```
+- For non-trivial implementation, create a fresh worktree from current `origin/main`:
+  ```bash
+  git worktree add ../core-<task-slug> origin/main -b <branch-name>
+  cd ../core-<task-slug>
+  ```
+- Run smoke suite, or record the exact local failure and use repo-native pytest lanes if the `core` CLI is unavailable.
+- Read the most recent relevant `HANDOFF-*.md`.
 
 ### Phase 1: Context & Scope
+
 - Paste the **Session Entry / Context Load** prompt from `docs/core-rd-base-prompts.md`.
 - Clearly state the exact scope and the invariant(s) you will preserve.
 
 ### Phase 2: Planning (Plan Mode Preferred)
+
 - Use **Plan Mode** for anything non-trivial.
 - Produce a clear plan with:
   - Modules affected
@@ -53,33 +102,55 @@ Every productive session follows this pattern:
   - Risk assessment
 
 ### Phase 3: Sweep
+
 - Run full import/call-site/eval sweep before any edit (use `pre-edit-sweep` skill when available).
 - Use the 1M context window aggressively.
 
 ### Phase 4: Implementation
+
 - Make minimal, load-bearing changes.
 - Write failing tests *before* behavior changes when possible.
 - Prefer explicit refusal over silent wrong answers.
 
 ### Phase 5: Verification
+
 - Run relevant test suites (smallest relevant first).
 - Run **Versor Coherence Guardian** checks on any algebra/field/vault/generate changes.
 - Run the **Standing Loop Axiom Check** (#7 from prompt library).
+- Verify PR hygiene before opening:
+  ```bash
+  git status --short
+  git diff --check origin/main...HEAD
+  git diff --name-status origin/main...HEAD
+  git log --oneline --reverse origin/main..HEAD
+  ```
+
+### Phase 6: Documentation, PR Summary & Handoff
 
-### Phase 6: Documentation & Handoff
 - Write/update the handoff document using `docs/handoff_template.md`.
 - Record exact invariants verified, tests run, and open tasks.
+- Every PR summary must include:
+  - branch name;
+  - commit list in order;
+  - exact changed files;
+  - exact tests/evals run and outputs;
+  - whether `wrong_total == 0` applies and held;
+  - known caveats;
+  - explicit non-goals;
+  - handoff content or handoff file path.
 
 ---
 
 ## 4. Using Grok Build Features at Mastery Level
 
 ### Plan Mode
+
 - Default for any change touching `algebra/`, `field/`, `vault/`, `generate/`, `teaching/`, `core/cognition/`, or `calibration/`.
 - Use it even for "small" refactors in sensitive areas.
 - Review the plan carefully before approval — this is your main defense against drift.
 
 ### Arena / Parallel Subagents
+
 - Powerful but high-risk if not structured.
 - Recommended pattern: Role separation
   - **Agent A**: ADR / invariant auditor
@@ -92,12 +163,13 @@ Every productive session follows this pattern:
 - Every subagent must independently satisfy core invariants before its output is considered.
 
 ### Skills System
+
 - Prefer skills over ad-hoc prompting for repeated patterns.
 - Currently available high-value skills:
-  - `core-bootstrap`
+  - `/core-bootstrap`
-  - `versor-coherence-guardian`
+  - `/versor-coherence-guardian`
-  - `pre-edit-sweep`
+  - `/pre-edit-sweep`
-  - `claim-proposal-guardian`
+  - `/claim-proposal-guardian`
 - Use `/skillify` after successful sessions to capture new reusable workflows.
 
 ---
@@ -122,6 +194,10 @@ The other sections (#2–#6) are used situationally depending on the type of wor
 - Running large changes without Plan Mode on sensitive modules
 - Letting Arena subagents edit without role separation and reconciliation
 - Skipping the bootstrap + smoke + handoff loop
+- Switching branches before inspecting dirty state
+- Deleting, resetting, or restoring unknown local work without classifying it
+- Pulling `main` without first fetching/pruning and verifying fast-forward state
+- Reusing stale branches for new tasks that should start from current `origin/main`
 - Using statistical/approximate solutions for exact CGA or epistemic requirements
 - Bypassing review gates for claim/pack/policy/identity mutations
 - Assuming "it probably didn’t touch the invariant" without verification
@@ -137,6 +213,7 @@ Before opening or merging any PR:
 3. Verify all touched invariants have explicit checks.
 4. Confirm relevant tests/evals are green with exact outputs recorded.
 5. Write a high-quality handoff document.
+6. Include a complete PR summary: branch, commits, changed files, tests/evidence, invariants, caveats, non-goals, and handoff.
 
 For docs/config/agent-governance PRs (like this one), smoke is usually sufficient. For runtime changes, full validation is required.
 
@@ -157,6 +234,27 @@ For docs/config/agent-governance PRs (like this one), smoke is usually sufficien
 # Bootstrap (in Grok Build TUI or via skill invocation)
 /core-bootstrap
 
+# Confirm root
+pwd
+git rev-parse --show-toplevel
+
+# Inspect local state before branch movement
+git status --short --branch
+git diff --stat
+git diff --name-status
+git diff --cached --name-status
+git stash list
+git worktree list
+
+# Establish clean current main
+git fetch origin --prune
+git switch main
+git pull --ff-only origin main
+
+# Create fresh worktree for non-trivial work
+git worktree add ../core-<task-slug> origin/main -b <branch-name>
+cd ../core-<task-slug>
+
 # Verify core invariant
 core test --suite algebra -q
 
@@ -169,4 +267,4 @@ grok inspect
 
 ---
 
-This document, combined with the files it references, represents the current best-known method for using Grok 4.3 + Grok Build on CORE with high discipline and low risk of architectural regression.
+This document, combined with the files it references, represents the current best-known method for using Grok 4.3 + Grok Build on CORE with high discipline and low risk of architectural regression.