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,40 @@
+# Why Version Control Exists
+
+## The problem: `final.txt`, `final_v2.txt`, `final_v2_ACTUALLY_FINAL.txt`
+
+Before version control, "keeping history" usually meant copying a file with a new name every
+time something changed. This fails fast: you lose track of WHAT changed between versions, WHO
+changed it, and WHY — and it gets completely unworkable the moment more than one person touches
+the same project.
+
+## What version control actually gives you
+
+- **History** — every change, in order, permanently. You can see exactly what a file looked
+  like at any point in the past.
+- **Reproducibility** — you can recreate the EXACT state of an entire project at any past
+  moment, not just one file.
+- **Collaboration** — multiple people can work on the same project without emailing files back
+  and forth or overwriting each other's work.
+- **A source of truth** — one authoritative history everyone agrees is correct, instead of
+  "whoever has the newest-looking filename."
+- **Rollback** — if a change turns out to be wrong, you can return to a known-good prior state
+  with confidence, not by hoping you kept a backup copy somewhere.
+
+## Why copying files isn't version control
+
+Copying `app.py` to `app_backup.py` before making a risky change LOOKS like version control, but
+it has none of version control's real properties: no record of WHY the change was made, no way
+to see incremental history, no way to combine two people's simultaneous edits, and no
+scalability past a handful of files. Git (and version control generally) tracks CHANGES over
+time as a structured history, not disconnected snapshots you have to manually manage.
+
+## Instructor Notes
+
+**Lesson goal:** Motivate Git before teaching a single command — students should feel the real
+problem (the `final_v2_ACTUALLY_FINAL.txt` pattern) before the solution makes sense.
+
+**Approximate timing:** 10 minutes read; 8 minutes live.
+
+**Discussion question:** "Has anyone ever lost work, or overwritten someone else's work, because
+of exactly this kind of file-copying problem?" (Real personal stories land this lesson far
+better than abstract description.)
@@ -0,0 +1,31 @@
+# Knowledge Check: Why Version Control Exists
+
+---
+
+**1. Name three real properties version control gives you that copying files as backups
+doesn't.**
+
+*Answer:* Any three of: structured history of every change, reproducibility of exact past
+states, real collaboration between multiple people, a single agreed-upon source of truth,
+confident rollback to a known-good state.
+
+---
+
+**2. Why does `final_v2_ACTUALLY_FINAL.txt` fail as a version-control strategy?**
+
+*Answer:* It has no record of what changed or why between versions, doesn't scale past a
+handful of files, and provides no way to merge two people's simultaneous changes.
+
+---
+
+**3. What does "source of truth" mean in the context of version control?**
+
+*Answer:* One authoritative, agreed-upon history of a project that everyone treats as
+correct — as opposed to ambiguity over which copy or filename is the "real" current version.
+
+## Instructor Notes
+
+**Facilitation:** Keep this brief — it's checking motivation/vocabulary before the hands-on
+modules begin, not testing depth yet.
+
+**Approximate timing:** 4 minutes.
@@ -0,0 +1,25 @@
+# Reflection: Naming the Problem You're About to Solve
+
+## Reflection questions
+
+1. Have you personally ever lost work, or been confused about which file version was current,
+   in a way version control would have prevented?
+2. What do you expect to feel DIFFERENT about how you work once you have real history and
+   rollback available?
+
+## Real Ops takeaway
+
+**Every engineering practice this program builds toward — code review, CI/CD, GitOps,
+infrastructure as code — assumes version control as its foundation.** You cannot meaningfully
+automate deployment, review changes before they ship, or declare infrastructure as code without
+first having a reliable, structured history of what changed and when. This module named the
+problem; the rest of ROOT 03 gives you the tool.
+
+This module is complete. Continue to the next module.
+
+## Instructor Notes
+
+**Discussion questions for a live classroom:** question 1 tends to produce genuine, motivating
+stories — let students share before moving to Module 2's mental model.
+
+**Approximate timing:** 5 minutes live discussion; 3 minutes self-paced writing.
@@ -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.
@@ -0,0 +1,70 @@
+# Everyday Git
+
+## The commands you'll actually use constantly
+
+Module 2 gave you the model. This module gives you the six commands that make up the vast
+majority of real, everyday Git usage.
+
+## `git init` — start tracking a project
+
+```
+$ git init
+```
+
+Creates a new, empty repository in the current directory (a hidden `.git` folder holds
+everything). You only run this ONCE per project, at the very beginning.
+
+## `git status` — where do things stand right now?
+
+Shows what's staged, what's modified-but-unstaged, and what's untracked — the single most
+useful command for orienting yourself, and one you'll run constantly, almost reflexively,
+before and after almost every other Git command.
+
+## `git add` — stage a change
+
+```
+$ git add file.txt        # stage one specific file
+$ git add .                # stage everything currently changed
+```
+
+## `git commit` — permanently record what's staged
+
+```
+$ git commit -m "Add configuration loader"
+```
+
+A good commit message describes WHAT changed and, ideally, WHY — future-you (or a teammate)
+reading `git log` months later should understand the change without re-reading the entire diff.
+
+## `git log` — see the history
+
+```
+$ git log --oneline
+a1b2c3d Add configuration loader
+9f8e7d6 Initial commit
+```
+
+## `git diff` — see exactly what changed, before you commit it
+
+```
+$ git diff              # unstaged changes vs. the last commit
+$ git diff --staged     # staged changes vs. the last commit
+```
+
+Reading your own diff before committing is one of the highest-value habits in this entire
+course — catching an accidental leftover debug line, or a change you didn't mean to include,
+BEFORE it becomes a permanent part of history.
+
+## Instructor Notes
+
+**Lesson goal:** Convert Module 2's model into the six commands used in nearly every real Git
+session — this is the fluency floor for everything that follows in ROOT 03.
+
+**Approximate timing:** 15 minutes read; 10 minutes live.
+
+**Common misconception to watch for:** treating `git add .` as always safe — it stages
+EVERYTHING changed, including files you might not have intended to include; `git status` before
+`git add .` is the habit that prevents this.
+
+**Demo idea:** run the full init→status→add→commit→log→diff sequence live, narrating `git
+status`'s changing output at each step.
@@ -0,0 +1,56 @@
+# Demonstration: The Full Cycle, End to End
+
+## OBSERVE
+
+```
+$ git init
+$ git status --short
+(nothing — empty repository)
+```
+
+## HYPOTHESIS
+
+Predict what happens to `git status` after creating a new file.
+
+## INSPECT
+
+```
+$ echo "v1" > app.py
+$ git status --short
+?? app.py
+```
+
+## CHANGE
+
+```
+$ git add app.py
+$ git diff --staged
+v1
+$ git commit -m "Add initial app.py"
+```
+
+`git diff --staged` shows exactly what's ABOUT to be committed — a real, final check before it
+becomes permanent.
+
+## VERIFY
+
+```
+$ git log --oneline
+3f9a1c2 Add initial app.py
+$ git status --short
+(clean)
+```
+
+The complete cycle, verified with real evidence at each step — not "I think I committed it,"
+but confirmed via `git log`.
+
+## Instructor Notes
+
+**Demo goal:** Show `git diff --staged` as the final safety check before a commit becomes
+permanent — a habit worth building explicitly, not just mentioning in passing.
+
+**Approximate timing:** 8 minutes live.
+
+**Common mistake to watch for:** skipping `git diff`/`git diff --staged` entirely and committing
+on faith — a good moment to ask "how would you know if you accidentally staged the wrong
+thing?"
@@ -0,0 +1,39 @@
+# Knowledge Check: Everyday Git
+
+---
+
+**1. What's the difference between `git diff` and `git diff --staged`?**
+
+*Answer:* `git diff` shows unstaged changes (working tree vs. last commit); `git diff --staged`
+shows what's currently staged and about to be committed (staging area vs. last commit).
+
+---
+
+**2. Why is `git add .` potentially risky compared to `git add <specific-file>`?**
+
+*Answer:* It stages EVERYTHING currently changed in the directory, which can accidentally
+include files you didn't mean to commit — checking `git status` first (or using targeted `git
+add`) avoids this.
+
+---
+
+**3. What makes a commit message actually useful months later?**
+
+*Answer:* Describing WHAT changed and ideally WHY, clearly enough that someone (including
+future-you) reading `git log` understands the change without re-reading the full diff.
+
+---
+
+**4. You run `git init` in a directory that already has an existing Git repository. What
+happens?**
+
+*Answer:* `git init` only needs to run once per project — running it again in an already-
+initialized repository is harmless (it won't destroy existing history) but is never actually
+necessary.
+
+## Instructor Notes
+
+**Facilitation:** Question 2 is a good moment to establish "check status before staging broadly"
+as a house habit for the rest of the course.
+
+**Approximate timing:** 5 minutes.
@@ -0,0 +1,32 @@
+# Guided Exercise: Plan a Real Commit Before You Make It
+
+This is a paper exercise — commit to a plan before working in the Lab.
+
+## Your task
+
+You've made three unrelated changes to your working tree: fixed a typo in `README.md`, added a
+new function to `utils.py`, and started (but not finished) an unrelated experiment in
+`scratch.py` you're not ready to commit. Write out the exact sequence of commands you'd use to
+end up with exactly ONE clean commit containing the README typo fix, leaving the other two files
+alone.
+
+## A worked shape to check yourself against
+
+```
+git status
+git add README.md
+git diff --staged
+git commit -m "Fix typo in README"
+git status
+```
+
+The key insight: `git add` lets you choose EXACTLY what goes into the next commit, regardless of
+what else is sitting, unstaged, in your working tree — `utils.py` and `scratch.py` remain
+untouched and uncommitted.
+
+## Instructor Notes
+
+**Facilitation:** This exercise directly tests whether Module 2's staging-area model actually
+stuck — if students reach for `git add .`, that's a sign to revisit the model before the Lab.
+
+**Approximate timing:** 8-10 minutes live discussion; 5 minutes self-paced.
@@ -0,0 +1,24 @@
+# Reflection: You Have Real, Permanent History Now
+
+## Reflection questions
+
+1. Look at your own `git log` from this module's Lab. Is your commit message something a
+   stranger (or future-you) could understand without more context?
+2. Which of the six commands from this module do you expect to type the most, going forward?
+
+## Real Ops takeaway
+
+**A real, permanent, inspectable history of your work now exists — this is the actual thing
+Module 1 named as missing from copy-a-file-as-backup.** Every commit you make from here on is
+recoverable, comparable, and explainable. Module 4 builds on this by letting multiple lines of
+work (branches) develop independently before combining — impossible without the reliable
+history you just built the habit of creating.
+
+This module is complete. Continue to the next module.
+
+## Instructor Notes
+
+**Discussion questions for a live classroom:** question 1 works well as a peer-review pass —
+have students read a neighbor's commit message and guess what it changed, then compare.
+
+**Approximate timing:** 5-8 minutes live discussion; 5 minutes self-paced writing.
@@ -0,0 +1,62 @@
+# Branching and Merging
+
+## Why branches exist
+
+Without branches, every commit happens on the same single line of history — risky work and
+finished work are indistinguishable, and two people can't develop different things
+simultaneously without directly interfering with each other. A **branch** is a movable pointer
+to a commit, letting you develop something in isolation and only combine it back into the main
+line when it's actually ready.
+
+## Creating and switching branches
+
+```
+$ git branch feature-login       # create a new branch (doesn't switch to it)
+$ git checkout feature-login     # switch to it
+$ git switch feature-login       # the newer, clearer equivalent of checkout for this purpose
+$ git checkout -b feature-login  # create AND switch in one step
+```
+
+Commits made while on `feature-login` only affect that branch — `main` is completely unaffected
+until you deliberately combine them.
+
+## Merging: combining two branches' history
+
+```
+$ git checkout main
+$ git merge feature-login
+```
+
+Git attempts to combine the two branches' history automatically. When the two branches changed
+DIFFERENT parts of a project, this usually succeeds with no fuss.
+
+## Divergence and conflicts
+
+When both branches changed the SAME lines of the SAME file differently, Git can't automatically
+decide which version is correct — this is a **merge conflict**. Git marks the conflicting
+section directly in the file:
+
+```
+<<<<<<< HEAD
+your current branch's version
+=======
+the incoming branch's version
+>>>>>>> feature-login
+```
+
+A conflict is not an error you did something wrong — it's Git correctly refusing to silently
+guess which change you actually want. You resolve it by editing the file to the content you
+actually want (removing the markers), then staging and committing to complete the merge.
+
+## Instructor Notes
+
+**Lesson goal:** Frame merge conflicts as an EXPECTED, normal part of collaborative work — not
+a sign of failure — before students hit their first real one in this module's Lab.
+
+**Approximate timing:** 15 minutes read; 10 minutes live.
+
+**Common misconception to watch for:** panicking at the sight of conflict markers — reinforce
+explicitly that this is Git behaving correctly, not breaking.
+
+**Demo idea:** deliberately narrate a conflict as "Git is asking YOU to make a decision it
+can't make safely on its own" rather than "something went wrong."
@@ -0,0 +1,61 @@
+# Demonstration: A Conflict, Caused and Resolved on Purpose
+
+## OBSERVE
+
+Two branches both changed line 1 of `config.txt` — `main` to `"env=production"`, `feature` to
+`"env=staging"`.
+
+## HYPOTHESIS
+
+Predict what `git merge feature` will do.
+
+## INSPECT
+
+```
+$ git merge feature
+Auto-merging config.txt
+CONFLICT (content): Merge conflict in config.txt
+Automatic merge failed; fix conflicts and then commit the result.
+```
+
+Exactly as predicted — Git refuses to guess.
+
+## CHANGE
+
+```
+$ cat config.txt
+<<<<<<< HEAD
+env=production
+=======
+env=staging
+>>>>>>> feature
+```
+
+Decide the real answer — here, say `env=production` is correct — and edit the file to exactly
+that, deleting all three marker lines.
+
+## VERIFY
+
+```
+$ git add config.txt
+$ git commit -m "Merge feature, keep production config"
+$ git log --oneline --graph
+*   a1b2c3d Merge feature, keep production config
+|\
+| * 9f8e7d6 Update from feature
+* | 3d2c1b0 Update from main
+|/
+* 0a1b2c3 Initial commit
+```
+
+The graph shows exactly what happened: two lines of history, deliberately combined.
+
+## Instructor Notes
+
+**Demo goal:** Walk a real conflict from cause to resolution without skipping any step,
+reinforcing that resolution means making an explicit CHOICE, not applying a trick.
+
+**Approximate timing:** 10 minutes live.
+
+**Common mistake to watch for:** leaving conflict markers accidentally in the "resolved" file
+(easy to miss one) — `grep '<<<<<<<' file` before committing catches this reliably.
@@ -0,0 +1,36 @@
+# Knowledge Check: Branching and Merging
+
+---
+
+**1. What is a branch, really?**
+
+*Answer:* A movable pointer to a specific commit — not a copy of the whole project, just a
+reference letting you develop independently from other branches.
+
+---
+
+**2. Why does a merge conflict happen?**
+
+*Answer:* Both branches changed the SAME lines of the SAME file differently, and Git can't
+safely guess which version you actually want — so it stops and asks you to decide.
+
+---
+
+**3. Is a merge conflict a sign something went wrong?**
+
+*Answer:* No — it's Git correctly refusing to silently guess at a decision only a human should
+make. It's a normal, expected part of collaborative work.
+
+---
+
+**4. After resolving a conflict by editing the file, what two steps complete the merge?**
+
+*Answer:* Stage the resolved file (`git add`) and commit (`git commit`) — exactly like
+completing any other commit, once the conflict markers are gone.
+
+## Instructor Notes
+
+**Facilitation:** Question 3 is worth stating explicitly and repeating — reframing conflicts
+as normal, not scary, meaningfully changes how confidently students approach this module's Lab.
+
+**Approximate timing:** 5 minutes.
@@ -0,0 +1,36 @@
+# Guided Exercise: Decide the Resolution Before You Touch the File
+
+This is a paper exercise — commit to a decision before resolving anything in the Lab.
+
+## Your task
+
+A merge conflict shows:
+
+```
+<<<<<<< HEAD
+timeout_seconds = 30
+=======
+timeout_seconds = 120
+>>>>>>> feature
+```
+
+You know `main`'s value (30) was set deliberately for production safety, but `feature`'s value
+(120) was added while debugging a slow endpoint that genuinely needs more time. Write out: what
+final content would you put in the file, and why is that the RIGHT resolution (not just "pick
+one side")?
+
+## A worked shape to check yourself against
+
+A well-reasoned resolution here is neither side alone: something like keeping `30` as the
+DEFAULT but adding a comment or a separate, more specific setting for the slow endpoint
+specifically — the point is that conflict resolution sometimes means genuinely combining intent
+from both sides, not mechanically picking `HEAD` or the incoming branch. There's no single
+"correct" file content — the value is in justifying whichever choice you make with real
+reasoning, not defaulting to whichever side happens to be `HEAD`.
+
+## Instructor Notes
+
+**Facilitation:** The point of this exercise is resisting "just pick a side" as a reflex —
+some conflicts genuinely require combining or renegotiating intent, not mechanical selection.
+
+**Approximate timing:** 8-10 minutes live discussion; 5 minutes self-paced.
@@ -0,0 +1,26 @@
+# Reflection: Your First Conflict Wasn't a Disaster
+
+## Reflection questions
+
+1. Before this module, how would you have reacted to seeing conflict markers in a real file
+   for the first time?
+2. What made resolving the conflict in this module's Lab feel manageable (or not)? What would
+   make a REAL conflict, in a large unfamiliar file, harder?
+
+## Real Ops takeaway
+
+**Merge conflicts are one of the most feared parts of Git for beginners, and one of the most
+routine parts of Git for experienced engineers — the difference is just repetition.** You've now
+caused one on purpose, resolved it deliberately, and verified the result — exactly the
+experience that turns "conflicts are scary" into "conflicts are Tuesday." Module 5 adds a real
+remote to this same workflow; conflicts show up there too, and you're now prepared for them.
+
+This module is complete. Continue to the next module.
+
+## Instructor Notes
+
+**Discussion questions for a live classroom:** question 2 is worth extending into "what would
+make a conflict on a 500-line file, with someone else's unfamiliar code, actually hard" — a good
+honest preview of real collaborative work.
+
+**Approximate timing:** 5-8 minutes live discussion; 5 minutes self-paced writing.
@@ -0,0 +1,56 @@
+# Remote Repositories
+
+## What a remote actually is
+
+Every repository you've worked with so far has been entirely LOCAL — on this one machine. A
+**remote** is a reference to another copy of the same repository, typically hosted somewhere
+else (a server, or in this Lab, a second local repository playing that role). Remotes are what
+make real collaboration possible: multiple people, multiple machines, all synchronizing through
+one shared history.
+
+## `origin`: a name, not a special concept
+
+By convention, the remote you cloned FROM is named `origin` — but this is just a label Git
+assigns automatically, not a technical requirement. You could name a remote anything; `origin`
+is simply the default everyone recognizes.
+
+## The four remote operations
+
+- **`git clone <url>`** — copy an ENTIRE remote repository (full history included) to a new
+  local directory, automatically configuring it as `origin`.
+- **`git fetch`** — download the remote's latest commits WITHOUT changing your own working
+  files or branches — a safe way to see what's new before deciding what to do about it.
+- **`git pull`** — fetch AND immediately merge the remote's changes into your current branch —
+  effectively `fetch` + `merge` in one step (which is exactly why a `pull` can produce a merge
+  conflict, the same as Module 4's local merges).
+- **`git push`** — upload your local commits to the remote, making them visible to everyone else
+  using that remote.
+
+## Upstream: your branch's remote counterpart
+
+A local branch can be configured to TRACK a specific remote branch (its "upstream") — once set,
+plain `git pull`/`git push` (no extra arguments) know exactly which remote branch to sync
+against, rather than requiring you to specify it every time.
+
+## RootNode uses Gitea (this course does not)
+
+RootNode's own engineering team uses Gitea (a self-hosted Git service) for its real work — the
+CONCEPTS in this lesson (origin, clone, fetch, pull, push) are identical regardless of which
+service hosts a remote (Gitea, GitHub, GitLab, or a private server). This course teaches those
+concepts using a disposable LOCAL repository standing in for a remote — no account, no network
+access, and no RootNode credentials are ever needed or exposed in this Lab.
+
+## Instructor Notes
+
+**Lesson goal:** Teach remotes as a genuine, transferable concept — students should be able to
+work with ANY real Git hosting service afterward, not just this Lab's local simulation.
+
+**Approximate timing:** 15 minutes read; 10 minutes live.
+
+**Common misconception to watch for:** treating `git pull` as a "safe, no-side-effects" command
+— it's a merge, and merges can conflict, exactly like Module 4 taught.
+
+**Discussion question:** "Why might a team prefer `git fetch` followed by manually reviewing
+changes, over always running `git pull` directly?" (Answer: fetch lets you see what changed
+before it touches your own working files/branch — useful caution before merging in unfamiliar
+changes.)
@@ -0,0 +1,56 @@
+# Demonstration: A Complete Clone-to-Push Round Trip
+
+## OBSERVE
+
+A bare (remote-style) repository already exists, currently empty.
+
+```
+$ git clone /srv/demo-remote.git /srv/demo-clone
+warning: You appear to have cloned an empty repository.
+```
+
+Cloning an empty remote is completely normal — it just means no commits exist there yet.
+
+## HYPOTHESIS
+
+Predict what `git remote -v` will show inside the new clone.
+
+## INSPECT
+
+```
+$ cd /srv/demo-clone && git remote -v
+origin  /srv/demo-remote.git (fetch)
+origin  /srv/demo-remote.git (push)
+```
+
+Automatically configured as `origin` — exactly as the lesson described, with no extra setup.
+
+## CHANGE
+
+```
+$ echo "# Demo Project" > README.md
+$ git add README.md
+$ git commit -m "Add README"
+$ git push origin main
+```
+
+## VERIFY
+
+```
+$ git --git-dir=/srv/demo-remote.git log --oneline
+3f9a1c2 Add README
+```
+
+Checking the REMOTE directly (not the clone) proves the push actually reached it — the commit
+now exists in two places, in sync.
+
+## Instructor Notes
+
+**Demo goal:** Prove the push actually worked by inspecting the REMOTE side independently,
+not just trusting the clone's own `git log`.
+
+**Approximate timing:** 8 minutes live.
+
+**Common mistake to watch for:** assuming a successful `git push` with no error message means
+success without ever double-checking — worth reinforcing the "verify independently" habit from
+earlier ROOT_ modules.
@@ -0,0 +1,40 @@
+# Knowledge Check: Remote Repositories
+
+---
+
+**1. What's the difference between `git fetch` and `git pull`?**
+
+*Answer:* `git fetch` downloads the remote's new commits without touching your working files or
+branches. `git pull` does that AND immediately merges them into your current branch — it's
+fetch + merge combined.
+
+---
+
+**2. Why can `git pull` produce a merge conflict?**
+
+*Answer:* Because it performs a real merge under the hood — if your local branch and the
+remote's branch both changed the same lines differently, the same conflict situation from
+Module 4 can occur.
+
+---
+
+**3. Is `origin` a required, special name Git enforces?**
+
+*Answer:* No — it's just the conventional default name Git assigns to the remote you cloned
+from. You could name a remote something else; `origin` is a widely recognized convention, not a
+technical requirement.
+
+---
+
+**4. Does this course require a GitHub or Gitea account to learn remotes?**
+
+*Answer:* No — this course uses a disposable local bare repository to safely simulate a real
+remote, teaching the same concepts (clone/fetch/pull/push/origin) without any account or network
+access.
+
+## Instructor Notes
+
+**Facilitation:** Question 2 is worth emphasizing — many students assume `pull` is risk-free
+until they hit their first real pull-conflict.
+
+**Approximate timing:** 5 minutes.
@@ -0,0 +1,30 @@
+# Guided Exercise: Fetch First, Decide Second
+
+This is a paper exercise — commit to a plan before working in the Lab.
+
+## Your task
+
+You're about to sync with a shared remote that a teammate has been actively pushing to all day.
+You're not sure what they changed. Write out the SAFER sequence of commands (as opposed to
+running `git pull` immediately), and explain what each step lets you verify before your own
+working files are touched.
+
+## A worked shape to check yourself against
+
+```
+git fetch origin
+git log HEAD..origin/main --oneline
+```
+
+`git fetch` downloads the new commits without touching your branch. The `log` command then
+shows you exactly what commits exist on the remote that you don't have locally yet — letting you
+review WHAT changed before deciding to merge it in with a subsequent `git merge origin/main` (or
+`git pull`, now that you already know roughly what to expect).
+
+## Instructor Notes
+
+**Facilitation:** This exercise directly builds the "fetch first, review, then merge" habit
+real teams use on shared branches — worth connecting explicitly to why blind `git pull` on a
+busy shared branch is a common source of surprise conflicts.
+
+**Approximate timing:** 8-10 minutes live discussion; 5 minutes self-paced.
@@ -0,0 +1,24 @@
+# Reflection: You Just Practiced Real Collaboration, Safely
+
+## Reflection questions
+
+1. What would have felt different about this module's Lab if the remote were a real hosted
+   service (Gitea/GitHub) instead of a local simulation? What would have felt the same?
+2. Where do you expect `push` to matter most in real engineering work you'll do later?
+
+## Real Ops takeaway
+
+**Everything you just practiced — clone, commit, push, verified independently on the remote
+side — is the exact mechanism behind CI/CD and GitOps, which ROOT 11 covers later.** A CI
+pipeline triggers because someone pushed; a GitOps deployment happens because a change was
+pushed to a Git repository treated as the source of truth. You haven't just learned Git commands
+— you've practiced the literal trigger mechanism modern deployment automation is built around.
+
+This module is complete. Continue to the final module of this course.
+
+## Instructor Notes
+
+**Discussion questions for a live classroom:** question 2 previews ROOT 11's GitOps content
+directly — worth naming that connection explicitly, even without teaching GitOps itself yet.
+
+**Approximate timing:** 5-8 minutes live discussion; 5 minutes self-paced writing.
@@ -0,0 +1,54 @@
+# Engineering Git Workflow
+
+## Small commits, meaningful messages
+
+A commit containing "fixed stuff" and 40 unrelated file changes is nearly useless to anyone
+reading history later — including future-you. A commit that does ONE logical thing, with a
+message describing what and why, is what actually makes `git log` a useful tool rather than
+noise. This isn't pedantry — it's what makes rollback (below) and code review actually
+practical.
+
+## `main` as a protected source of truth
+
+Real engineering teams treat their main branch as the one everyone trusts to be in a working
+state at all times — direct, unreviewed pushes to `main` are typically restricted specifically
+BECAUSE it's the shared source of truth every deployment and every other branch is built from.
+Feature branches (Module 4) exist precisely so risky, in-progress work never threatens that
+trust.
+
+## Review: another set of eyes before history is permanent
+
+Before a change reaches `main`, most real teams have someone else look at it first (a "pull
+request" or "merge request," depending on the platform). This isn't about distrust — it's a
+second perspective catching mistakes, and a natural point to discuss WHY a change is being made,
+not just what it does.
+
+## History and rollback as safety nets
+
+Because every commit is permanent and inspectable, a bad change can be identified precisely (via
+`git log`) and reverted deliberately — confident recovery, not panic, when something goes wrong.
+This is Module 1's original promise, now fully realized: reproducibility and rollback aren't
+theoretical, they're what your daily small-commit discipline actually buys you.
+
+## Why this matters to DevOps, GitOps, and Infrastructure as Code
+
+Everything in this lesson — small deliberate changes, a trusted source of truth, review before
+merge, reliable history — is EXACTLY what CI/CD pipelines automate, what GitOps treats a Git
+repository as authoritative for, and what Infrastructure as Code relies on to safely manage real
+infrastructure through the same discipline you just practiced on plain text files. ROOT 11
+builds directly on this course's habits, not a new set of ideas.
+
+## Instructor Notes
+
+**Lesson goal:** Close ROOT 03 by explicitly naming the professional discipline (not just Git
+commands) this course was building, and its direct connection to DevOps/GitOps/IaC.
+
+**Approximate timing:** 15 minutes read; 10 minutes live.
+
+**Common misconception to watch for:** treating "review" and "protecting main" as bureaucratic
+overhead rather than genuine risk management — connect it back to the real cost of a bad change
+reaching a shared source of truth unreviewed.
+
+**Discussion question:** "Why might a team enforce small commits and review even when working
+alone on a personal project?" (Good answers: future-you benefits from the same clarity; building
+the habit now pays off the moment you DO work with others.)
@@ -0,0 +1,47 @@
+# Demonstration: The Same Change, Told Two Ways
+
+## OBSERVE
+
+```
+$ git log --oneline
+a1b2c3d fixed stuff
+```
+
+One commit, an unhelpful message, and (imagine) 15 unrelated files changed together: a bug fix,
+a typo correction, and an unrelated half-finished experiment.
+
+## HYPOTHESIS
+
+Predict: six months from now, could you (or a teammate) confidently `git revert` just the bug
+fix from this commit, leaving the other 14 files untouched?
+
+## INSPECT
+
+No — reverting this ONE commit reverts everything in it together, including the unrelated
+typo fix and experiment, whether you want that or not.
+
+## CHANGE
+
+The same work, done as three separate, well-described commits instead:
+
+```
+$ git log --oneline
+3f9a1c2 Fix null-pointer crash in payment retry logic
+9d8e7f6 Fix typo in onboarding email template
+1a2b3c4 WIP: experiment with new caching strategy (not ready)
+```
+
+## VERIFY
+
+Now `git revert 3f9a1c2` cleanly undoes JUST the payment bug fix, with zero effect on the other
+two — because each commit is one logical, independently-reversible unit of work.
+
+## Instructor Notes
+
+**Demo goal:** Make the practical cost of "fixed stuff" commits concrete — not a style
+preference, a genuine loss of capability (precise revert, clear history, easier review).
+
+**Approximate timing:** 8 minutes live.
+
+**Common mistake to watch for:** treating this as a purely aesthetic preference rather than a
+practical one — reinforce the concrete "can you revert just the bug fix" test.
@@ -0,0 +1,32 @@
+# Knowledge Check: Engineering Git Workflow
+
+---
+
+**1. Why does bundling unrelated changes into one commit cost you something real, not just
+style points?**
+
+*Answer:* It makes precise operations like `git revert` impossible to apply to just ONE logical
+change — reverting the commit reverts everything in it together, whether you want that or not.
+
+---
+
+**2. Why do teams typically restrict direct, unreviewed pushes to `main`?**
+
+*Answer:* `main` is the shared source of truth everything else (deployments, other branches) is
+built from — protecting it reduces the chance an unreviewed mistake reaches something everyone
+else depends on being trustworthy.
+
+---
+
+**3. Name one concrete way this course's Git discipline connects to GitOps or CI/CD.**
+
+*Answer:* Any reasonable answer connecting small deliberate changes / a trusted source of truth
+/ review-before-merge / reliable history to how CI/CD pipelines trigger on pushes or how GitOps
+treats a Git repository as the authoritative record of desired infrastructure state.
+
+## Instructor Notes
+
+**Facilitation:** Question 3 is open-ended by design — the goal is students making the
+connection in their own words, not reciting a fixed answer.
+
+**Approximate timing:** 5 minutes.
@@ -0,0 +1,30 @@
+# Reflection: You've Practiced Real Engineering Discipline, Not Just Syntax
+
+## Reflection questions
+
+1. Look back across all six modules of ROOT 03. Which single habit (small commits, checking
+   `git status` before staging, fetch-before-pull, resolving conflicts deliberately) do you
+   think will matter most in real work?
+2. This course started with "copying files as backup isn't version control." Can you now
+   explain, in one sentence, what Git actually gives you that copying never could?
+
+## Real Ops takeaway
+
+**Version control discipline is not a Git-specific skill — it's an engineering discipline that
+happens to be exercised through Git.** Small deliberate changes, a trusted shared source of
+truth, review before permanent history, and confident rollback are the same principles behind
+CI/CD, GitOps, and Infrastructure as Code, all covered later in ROOT 11. You are not starting
+that content from zero — you already practiced its foundation here.
+
+This module — and ROOT 03 — is complete. Continue to ROOT 04: Containers & Docker.
+
+## Instructor Notes
+
+**Discussion questions for a live classroom:** question 2 is a good closing check — a clear,
+confident answer here is real evidence the course's central premise landed.
+
+**Approximate timing:** 8-10 minutes live discussion; 5 minutes self-paced writing.
+
+**Milestone note:** this is the last module of ROOT 03 — consider a brief recap connecting all
+six modules (why version control → the three-area model → everyday commands → branching/
+conflicts → remotes → professional workflow) before moving to ROOT 04.