diff --git a/docs/grokbuild/README.md b/docs/grokbuild/README.md index d2cab76b..4abfb262 100644 --- a/docs/grokbuild/README.md +++ b/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) -- Invoke the `core-bootstrap` skill (or run it manually via the Grok Build interface). +### Phase 0: Bootstrap + Workspace Hygiene (Mandatory) + +- Invoke `/core-bootstrap` or run the skill manually through Grok Build. - Read `GROK.md` + `AGENTS.md` + `docs/runtime_contracts.md`. -- Run smoke suite. -- Read most recent relevant `HANDOFF-*.md`. +- Confirm the current directory and repository root before any operation: + ```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 -- + git log --oneline --decorate --all -- + 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 : " -- + ``` +- 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- origin/main -b + cd ../core- + ``` +- 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` - - `versor-coherence-guardian` - - `pre-edit-sweep` - - `claim-proposal-guardian` + - `/core-bootstrap` + - `/versor-coherence-guardian` + - `/pre-edit-sweep` + - `/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- origin/main -b +cd ../core- + # 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. \ No newline at end of file +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.