From 8830e91846056f9ea72352821cfa1fc261fb28e7 Mon Sep 17 00:00:00 2001 From: claude Date: Mon, 22 Jun 2026 16:16:09 -0400 Subject: [PATCH] Capstone recovery + M11 lab honesty (#8,#14,#15,#30) (#60) Co-authored-by: claude Co-committed-by: claude --- capstone/README.md | 42 ++++++++++----- .../README.md | 51 +++++++++++++++---- 2 files changed, 70 insertions(+), 23 deletions(-) diff --git a/capstone/README.md b/capstone/README.md index c59347d..2a173ad 100644 --- a/capstone/README.md +++ b/capstone/README.md @@ -46,7 +46,7 @@ already standing; it doesn't re-pour the foundation. Pick something small enough to finish in one sitting and real enough to touch the whole stack. We'll add **due dates**: -- A task can carry an optional due date: `python cli.py add "file taxes" --due 2026-07-15`. +- A task can carry an optional due date: `python cli.py add "file taxes" --due `. - A new `overdue` command lists pending tasks whose due date has already passed. - The deployed service grows a matching `GET /overdue` endpoint, so the change is visible in the running container, not just the CLI. @@ -113,10 +113,12 @@ image from your `Dockerfile` (M16), tags it with the new commit SHA (immutable, rolls back to the previous SHA. Hit `GET /overdue` on the running container. The feature is live, in a reproducible artifact, behind a health check that can undo itself. -**If it goes wrong (M12).** Something slips past every gate eventually. A bad merge reverts cleanly -with `git revert -m 1 ` — a new commit, safe on shared history, no rewriting what teammates -pulled (M12). A bad deploy is already handled by `deploy.sh`'s rollback to the last good SHA. Recovery -is a discipline you rehearsed, not a panic. +**If it goes wrong (M12).** Something slips past every gate eventually. Because you squash-merged (one +commit on `main`, not a two-parent merge), a bad change reverts cleanly with plain +`git revert ` — a new commit, safe on shared history, no rewriting what teammates pulled +(M12). Skip the `-m 1` you saw in Module 12: that flag is only for true merge commits, the kind +`git merge --no-ff` makes, and a squash merge isn't one. A bad deploy is already handled by +`deploy.sh`'s rollback to the last good SHA. Recovery is a discipline you rehearsed, not a panic. That's the whole motion. Notice what carried it: not the model. **The model wrote the diff; the workflow is everything that made the diff safe to merge and trivial to undo.** Swap the model next @@ -164,14 +166,18 @@ account, and a working Docker install. committed instructions file (M5). If the agent reaches for a date library or hand-edits the JSON, your file needs a line; that's signal, not failure. -4. Run it by hand to confirm it's real: +4. Run it by hand to confirm it's real. Choose the two dates relative to *your* today — one comfortably + in the future, one safely in the past — so the assertion below holds whenever you run this: ```bash - python cli.py add "file taxes" --due 2026-07-15 - python cli.py add "renew domain" --due 2020-01-01 + python cli.py add "file taxes" --due # future → NOT overdue + python cli.py add "renew domain" --due 2020-01-01 # past → overdue python cli.py overdue # should list "renew domain", not "file taxes" ``` + > *Verify-before-publish: refresh the example due dates so the "future" one is still in the future + > at publish time — a hardcoded near-future date silently inverts this assertion once it passes.* + ### Part C — Tests (M13) 5. Have the AI extend `test_tasks.py`, then **read the test names** and confirm the boundaries are @@ -226,16 +232,28 @@ account, and a working Docker install. ### Part F — Rehearse recovery (M12) -11. Prove you can undo it. Find the merge commit and revert it on a throwaway branch, just to watch it - work, then delete the branch: +11. **Sync local `main` first.** The squash-merge in step 9 happened on the forge, so the new commit + lives only on the remote — your local `main` is one behind. Pull it down and capture the SHA of + the squash commit you're about to rehearse undoing: + + ```bash + git switch main && git pull # bring the squash-merge commit into local main + git log --oneline -1 # the top line IS your squash commit — note its SHA + ``` + +12. Prove you can undo it. Cut a throwaway branch off the freshly-synced `main` and revert that squash + commit, just to watch it work, then delete the branch: ```bash git switch -c throwaway-revert-test - git revert -m 1 # clean undo of the whole feature, as a new commit + git revert # plain revert: a squash merge is one ordinary commit, so no -m 1 pytest && git switch main && git branch -D throwaway-revert-test ``` - You just confirmed the escape hatch is real *before* you ever need it in anger. + No `-m 1` here, and nothing to "find": that flag is only for the two-parent merge commits Module 12 + rehearsed with `git merge --no-ff`. A squash merge produces a single-parent commit, so plain + `git revert ` is the right undo. You just confirmed the escape hatch is real *before* + you ever need it in anger. --- diff --git a/modules/11-collaboration-humans-and-agents/README.md b/modules/11-collaboration-humans-and-agents/README.md index 54c2dd9..7744b2c 100644 --- a/modules/11-collaboration-humans-and-agents/README.md +++ b/modules/11-collaboration-humans-and-agents/README.md @@ -267,8 +267,10 @@ loop, not the code, is what you're practicing. issues and PRs. - Push access to that repo (it's yours, so you have it). - Your editor-integrated AI tool (Module 4). -- Optionally, your host's CLI (`gh` for GitHub, `glab` for GitLab, `tea` for Gitea/Forgejo) — the web - UI works for everything here, so the CLI is convenience, not a requirement. +- Your host's CLI (`gh` for GitHub, `glab` for GitLab, `tea` for Gitea/Forgejo). The web UI covers the + whole human-driven loop (Parts A–D), so there the CLI is just convenience. Part E is the exception: + for an *agent* to open the PR itself it has to reach the forge, which needs the CLI installed and + authenticated — or you take the no-CLI fallback that section spells out. Starter artifacts are in this module's `lab/`: `issue.md` (the issue to file) and `pr-body.md` (the PR description, including the load-bearing closing keyword). @@ -320,11 +322,16 @@ If the push went through, protection isn't on — fix that before continuing. Fe the CLI), and it does what you asked. Run it: ```bash - python cli.py add "keeper" ; python cli.py add "trash" ; python cli.py done 1 + python cli.py add "keeper" ; python cli.py add "trash" + python cli.py list # note the index shown next to "trash" + python cli.py done # use the index "list" just printed — NOT a fixed 1 python cli.py clear-done # expect it to remove the completed one python cli.py list # "keeper" remains, "trash" is gone ``` + Read the index off `list` rather than assuming it: `done` is positional, and your `tasks-app` has + been carrying tasks since Module 1, so "trash" won't reliably land at index 1. + 5. Commit and push the branch: ```bash @@ -363,16 +370,38 @@ If the push went through, protection isn't on — fix that before continuing. Fe Run the loop one more time, but this time **let an agent be the contributor for steps 2–6.** File a second issue (e.g. "Add a `pending` command that lists only incomplete tasks" — the `TaskList.pending()` -method already exists, so this is wiring only). Then prompt your agent: +method already exists, so this is wiring only). -> "Take issue #43. Create a branch named `43-pending-command`, implement the feature, commit -> referencing the issue with a closing keyword, push the branch, and open a PR into `main` whose -> description closes #43." +**First, a reality check the rest of the lab let you skip.** Two of those steps cross the forge +boundary: the agent has to *read* issue #43 from the forge and *open* a PR back into it. Your Module 4 +editor agent only edits files and runs local commands — and `git push` publishes a branch, it does +**not** open a PR. The web UI you've been clicking can't be handed to the agent. So before you prompt, +give the agent a way to reach the forge. Pick one path: -Let the agent drive to the open-PR state. Then **you** are the human at the gate: review the diff, -and merge (or request changes) yourself. You've just watched the exact loop run with a non-human -contributor — and felt precisely where you, the human, stayed in it. If you want the parallel-agents -case, file two issues and run two agents in separate worktrees (Module 7), each on its own branch. +- **Full agent-opens-PR path (host CLI required).** Install and authenticate your host's CLI (`gh`, + `glab`, or `tea`) so the agent can run, e.g., `gh pr create` itself. For *this* step the CLI is a + requirement, not the convenience it was in Parts A–D. Then prompt the agent: + + > "Take issue #43. Create a branch named `43-pending-command`, implement the feature, commit + > referencing the issue with a closing keyword, push the branch, and open a PR into `main` whose + > description closes #43." + +- **No-CLI fallback (you open the PR).** Have the agent do everything local — branch, implement, + commit, push — and *you* open the PR in the web UI, reusing `lab/pr-body.md` and keeping the + `Closes #43` line. Prompt it the same way, but stop it at the push: + + > "Take issue #43. Create a branch named `43-pending-command`, implement the feature, commit + > referencing the issue with a closing keyword, and push the branch. I'll open the PR." + + Wiring an agent *directly* into the forge — so it reads issues and opens PRs with no human hand-off + and no CLI to shell out to — is what an MCP forge integration buys you in **Module 20**. Here you're + feeling the exact seam that module closes. + +Either way, let the agent drive to the open-PR state. Then **you** are the human at the gate: review +the diff, and merge (or request changes) yourself. You've just watched the exact loop run with a +non-human contributor — and felt precisely where you, the human, stayed in it. If you want the +parallel-agents case, file two issues and run two agents in separate worktrees (Module 7), each on its +own branch. ---