feat(root03): author Git & Collaborative Development

Adds all 6 ROOT 03 modules (why version control exists, the Git mental model, everyday Git, branching & merging, remote repositories, engineering Git workflow) — 31 activities. Uses only real LOCAL Git repositories throughout — no Gitea account, no network access, and no RootNode-canonical-repo credential is ever needed or exposed in a student Lab (docs/ROOT_FOUNDATIONS_LAB_STRATEGY.md §4). Modules 1, 2, and 6 are conceptual bookends with no lab, matching the flexible readiness standard already used in ROOT 01/02. Adds 3 new hands-on Git scenarios plus 2 MCQs: git-everyday-basics (init/add/commit, validated by inspecting real `git log`/`git show` state, not just command output strings — Step 6's explicit requirement), git-branching-and-merge (a REAL merge conflict caused on purpose by two branches editing the same line, resolved by the student, validated by confirming the conflict markers are gone and a real two-parent merge commit exists), and git-remote-clone-push (a real local bare repository standing in for a remote — clone/commit/push validated by inspecting the REMOTE side directly, not just the student's own clone). All tested end-to-end via the real scenario-validation API, including negative tests. Wires rootnode-git-fundamentals-assessment (2 required + 3 random-draw scenarios) using the existing Phase 3B assessment engine. Co-Authored-By: Claude Sonnet 5 <[email protected]>
2026-08-26 17:08:00 -05:00
parent e007bcf000
commit e68b6f445a
33 changed files with 1393 additions and 0 deletions
@@ -0,0 +1,59 @@
+# Git Mental Model
+
+## Three places your files can be
+
+Git tracks your project through three distinct areas, and understanding this model is what
+makes every Git command make sense — memorizing commands without it just produces confusion the
+first time something doesn't behave as expected.
+
+```
+Working Tree  →  Staging Area  →  Repository (commit history)
+(your actual        (what you've         (permanent,
+ files, as you       marked ready          recorded
+ edit them)          to commit)            snapshots)
+```
+
+- **Working tree** — the actual files on disk, exactly as you're editing them right now.
+- **Staging area** (also called "the index") — a holding area for changes you've deliberately
+  marked as ready to be committed. This is Git's most distinctive design choice: you don't
+  commit "everything that changed," you commit "exactly what you staged."
+- **Repository** — the permanent, recorded history of every commit ever made — this is what
+  `git log` shows you.
+
+## Why `git add` exists at all
+
+A change starts in your working tree. `git add <file>` moves it (conceptually — the mechanics
+are more subtle, but this framing is enough for now) into the staging area. `git commit` takes
+EVERYTHING currently staged and permanently records it as a new snapshot in the repository's
+history. This two-step process (stage, then commit) exists so you can build up a commit
+DELIBERATELY — staging exactly the related changes that belong together, even if your working
+tree currently has other, unrelated changes you're not ready to commit yet.
+
+## Core vocabulary
+
+- **Commit** — one permanently recorded snapshot, with a message describing what changed and
+  why, and a unique identifier (a hash).
+- **Branch** — a movable pointer to a specific commit, letting you develop something (a
+  "feature branch") without affecting the main line of history until you're ready to combine it
+  back in (Module 4).
+- **HEAD** — Git's pointer to "which commit you're currently looking at" — almost always the
+  tip of whichever branch you have checked out.
+- **Remote** — a reference to another copy of the same repository, usually hosted somewhere else
+  (Module 5).
+
+## Instructor Notes
+
+**Lesson goal:** Establish the three-area model BEFORE any commands — same "model before syntax"
+pedagogy as ROOT 01's process model and ROOT 05's Kubernetes mental model. Every subsequent Git
+command should be explainable in terms of moving something between these three areas.
+
+**Approximate timing:** 15 minutes read; 10 minutes live, ideally with a literal diagram drawn
+live (whiteboard or shared screen) showing files moving between the three areas.
+
+**Common misconception to watch for:** assuming `git commit` commits every changed file
+automatically — this is the single most common Git surprise for beginners, and it's exactly
+what Module 3's Lab will make concrete.
+
+**Discussion question:** "Why would you ever WANT to stage only some of your changes, not all
+of them?" (Answer: to build one commit about ONE logical change, even if your working tree
+currently has several unrelated edits in progress.)
@@ -0,0 +1,55 @@
+# Demonstration: Watching a File Move Between the Three Areas
+
+## OBSERVE
+
+```
+$ echo "draft" > report.txt
+$ git status --short
+?? report.txt
+```
+
+`??` means: Git sees this file, but it's in neither the staging area nor the repository yet —
+purely in the working tree.
+
+## HYPOTHESIS
+
+Predict what `git status` will show after `git add report.txt`.
+
+## INSPECT
+
+```
+$ git add report.txt
+$ git status --short
+A  report.txt
+```
+
+`A` (in the LEFT column, which represents the staging area) means: staged, ready to commit.
+
+## CHANGE
+
+```
+$ git commit -m "Add report draft"
+$ git status --short
+(nothing — clean)
+```
+
+## VERIFY
+
+```
+$ git log --oneline -1
+a1b2c3d Add report draft
+```
+
+The file traveled through all three areas exactly as the model predicts: working tree (`??`) →
+staging area (`A`) → repository (a permanent commit in `git log`).
+
+## Instructor Notes
+
+**Demo goal:** Make `git status`'s output legible by directly connecting its symbols (`??`, `A`,
+clean) to the three-area model just taught, rather than treating them as arbitrary codes to
+memorize.
+
+**Approximate timing:** 8 minutes live.
+
+**Common mistake to watch for:** students reading `git status` output without connecting it
+back to WHICH of the three areas each symbol refers to — reinforce the mapping explicitly.
@@ -0,0 +1,36 @@
+# Knowledge Check: Git Mental Model
+
+---
+
+**1. Name the three areas a file passes through, in order.**
+
+*Answer:* Working tree → staging area → repository (commit history).
+
+---
+
+**2. What does `git add` actually do, in terms of this model?**
+
+*Answer:* Moves a change from the working tree into the staging area — marking it as ready to
+be included in the next commit.
+
+---
+
+**3. If you edit three files but only `git add` one of them, what happens when you `git
+commit`?**
+
+*Answer:* Only the staged file is included in the new commit — the other two edited-but-unstaged
+files remain as uncommitted changes in the working tree.
+
+---
+
+**4. What is HEAD?**
+
+*Answer:* Git's pointer to the commit you're currently looking at — almost always the tip of
+whichever branch you have checked out.
+
+## Instructor Notes
+
+**Facilitation:** Question 3 is the single most important check in this module — if students
+get this wrong, revisit the diagram before continuing to Module 3.
+
+**Approximate timing:** 5 minutes.
@@ -0,0 +1,31 @@
+# Guided Exercise: Predict `git status` Before You See It
+
+This is a paper exercise — commit to a prediction before checking it in the Lab.
+
+## Your task
+
+Starting from a clean repository (nothing staged, nothing modified), predict what `git status
+--short` would show after EACH of these actions, in sequence:
+
+1. `echo "v1" > file.txt` (a brand new file)
+2. `git add file.txt`
+3. `echo "v2" >> file.txt` (modifying the ALREADY-STAGED file further)
+4. `git commit -m "Add file"`
+
+## A worked shape to check yourself against
+
+1. `?? file.txt` — untracked, in the working tree only.
+2. `A  file.txt` — staged (left column).
+3. `AM file.txt` — this is the surprising one: staged (`A`, left column) AND modified again
+   since staging (`M`, right column) — the staging area has a SNAPSHOT from step 2, and your
+   further edit in step 3 hasn't been staged yet.
+4. Clean (nothing) — but only the STAGED version (from step 2, without the step-3 edit) actually
+   got committed; the step-3 edit remains as an uncommitted modification afterward.
+
+## Instructor Notes
+
+**Facilitation:** Item 3 is deliberately the hardest — it's the exact scenario that surprises
+real beginners ("I thought I already staged this file, why does it show changes again?"). Worth
+slowing down on.
+
+**Approximate timing:** 10-12 minutes live discussion; 8 minutes self-paced.
@@ -0,0 +1,25 @@
+# Reflection: The Model Explains the Commands, Not the Other Way Around
+
+## Reflection questions
+
+1. Before this module, would `git add` before `git commit` have seemed like an unnecessary
+   extra step? Why does it actually matter now?
+2. Which of the three areas (working tree, staging, repository) do you feel least confident
+   distinguishing? What would help solidify it?
+
+## Real Ops takeaway
+
+**Every Git confusion you'll ever hit traces back to one of these three areas.** "Why isn't my
+change in the commit," "why does `git status` show something weird," "why did my commit include
+something I didn't mean to" — all of them are answerable by asking "which of the three areas is
+this change actually in right now?" You now have that question available; Module 3 makes it
+muscle memory.
+
+This module is complete. Continue to the next module.
+
+## Instructor Notes
+
+**Discussion questions for a live classroom:** question 2 is worth a quick poll — knowing where
+the class is least confident tells you where to slow down in Module 3's hands-on Lab.
+
+**Approximate timing:** 5-8 minutes live discussion; 5 minutes self-paced writing.