diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d77b829..b3e4968 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Contributing to GitUnstuck Thanks for your interest in contributing. GitUnstuck is a dependency-free, -client-side application: `index.html`, shared `recovery.js`, SVG assets and automated tests. +client-side application: `index.html`, shared `recovery.js` and `learning.js`, SVG assets and automated tests. We welcome contributions that keep it small, private, and easy to run. ## How to contribute @@ -22,7 +22,7 @@ We welcome contributions that keep it small, private, and easy to run. ## Coding conventions - **Zero dependencies.** Do not add npm packages, external fonts, external - scripts or runtime frameworks. Preserve the existing build-only minifiers. Source use opens `index.html` alongside `recovery.js`. + scripts or runtime frameworks. Preserve the existing build-only minifiers. Source use opens `index.html` alongside `recovery.js` and `learning.js`. - **Privacy first.** Pasted terminal output stays in the browser tab. Never transmit input over the network, and do not log or store it. - **Risk-aware guidance.** Every destructive command must be paired with a @@ -37,8 +37,10 @@ We welcome contributions that keep it small, private, and easy to run. - `index.html` — markup, styles, navigation and rendering. - `recovery.js` — shared recipe data and diagnosis logic. +- `learning.js` — canonical lessons, controlled Git/editor actions, manifests, routes and pure transitions. - `tests/test-analyzer.js` — parser, data and source assertions. - `tests/test-recovery.js` — executable disposable-repository scenarios. +- `tests/test-learning.js` — all lesson and independent-task outcomes, reference/parent checks and actual shell setup runs. - `tests/test-browser.cjs` — optional browser journey and presentation checks. - `docs/` — plans, feature specifications, and design notes. - `.github/` — CI workflows, issue/PR templates, and funding configuration. @@ -47,6 +49,14 @@ We welcome contributions that keep it small, private, and easy to run. Keep parser checks, executable recovery evidence and browser checks distinct. Tests must execute the same recipe definitions as the UI and assert protected file/index/history state. Do not treat matching source strings as proof that a recovery works. See README.md for supported environments and provider limitations. +## Teaching changes + +Before adding a lesson or control, name the learner difficulty, the resulting behaviour and a meaningful check. Keep the bounded sequence in `docs/learning-implementation.md`; record evidence and gaps in `docs/learning-evidence.md`. Additional topics need an explicit unmet need rather than a larger course outline. + +Define a stable lesson/checkpoint ID, prerequisites, fresh named practice setup, initial/final file/index/reference manifests, controlled action arrays, expected observations, prediction feedback, a changed independent task with a worked answer, and relevant reference/source links. Reuse the practice setup helper and canonical recovery prerequisites/consequences. Never execute lesson prose or learner-provided commands. Test actual repository contents and relationships, plus any new Bash/PowerShell syntax in those shells. Preserve old hashes and validated return context. + +Run `npm test`, `npm run build:check`, and `npm run build`; then run `node tests/test-browser.cjs` against source and the built artifact with an installed Playwright/Chromium environment. Keep build fingerprints aligned with tested inputs. Real beginner observations, older-Git runtime compatibility and unavailable accessibility checks must be reported separately from automated passes. Do not mark real learner validation complete using simulated beginners. + ## Code of Conduct All participants are expected to follow the diff --git a/README.md b/README.md index 5cbe993..0e022e8 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ GitUnstuck is a browser guide with three destinations: - **Fix a problem:** paste Git output or choose a specific recovery path. Read the prerequisites, run one step at a time, and verify the result. -- **Learn Git:** follow the existing lessons on repositories, staging, commits, branches and remotes. +- **Learn Git:** optional setup followed by six practical lessons: inspect, staging, history, branches/merges, remotes, and recovery. Each uses a fresh plain-text practice project, a prediction, observations, and an independent task. - **Find a command:** search the command reference for syntax, effects and examples. Pasted terminal content is processed in the current tab. The app does not upload or save that content. Theme and display preferences use local storage. No account or runtime package installation is required. @@ -22,7 +22,9 @@ Protected-branch guidance creates and publishes a new review branch. It does not ## Run and check locally -Open `index.html` alongside `recovery.js` and the SVG assets in a modern browser. Source checkout use needs no build. Commands in the guide use Git 2.23+ syntax and ordinary double-quoted paths. Replace uppercase placeholders before running a command; paths containing shell expansion characters or quotes need shell-specific quoting. Do not paste credentials into the guide. +Open `index.html` alongside `recovery.js`, `learning.js` and the SVG assets in a modern browser. Source checkout use needs no build. `#learn` opens the outline; `#learn/staging/edited-v3` opens a specific checkpoint. Lesson reference links retain their validated checkpoint through reload and search. Browser controls change illustrations only; the page cannot inspect or grade a real repository. + +Commands use Git 2.23+ syntax. Current learning fixtures ran on Git 2.56.0.windows.4; actual Git 2.23 runtime compatibility remains unverified. Bash and Windows PowerShell 5.1 setup blocks were executed in their actual shells. Use a fresh named directory for each lesson; practice identity, hook, signing and pager settings stay local. Replace uppercase reference placeholders with checked values; paths containing shell expansion characters or quotes need shell-specific quoting. Do not paste credentials into the guide. With Node.js 22 or later and Git installed: @@ -30,7 +32,7 @@ With Node.js 22 or later and Git installed: npm test ``` -This runs parser/source checks and disposable-repository integration tests. On the implementation machine, 194 parser/data/source assertions and 33 recovery scenarios passed. The Ubuntu CI suite exercises Bash; Windows additionally runs the PowerShell scenario. Source-string assertions only establish markup/data properties; the integration tests establish repository outcomes. +This runs parser/source checks, recovery integration tests, and the learning data/real-Git suite. Current Windows runs passed 194 analyzer assertions, 33 recovery scenarios and all seven lesson setups/worked examples/independent tasks. Learning setup was executed in Git Bash and Windows PowerShell 5.1. Checked-in CI workflows run Ubuntu with Node 22; there is no checked-in Windows job. Local validation used Node 26.12.1. Source-string assertions establish markup properties; Git fixtures establish repository outcomes. The recovery tests use temporary repositories and local bare remotes. They inspect actual file contents, index snapshots, untracked files, commit reachability and remote history. Coverage includes full staged-diff review, fetched outgoing-secret history, everyday remote updates in equal/ahead/behind/diverged states, latest and earlier secrets, dirty protected-branch recovery, main/master/custom branches, custom remotes, paths with spaces, existing backup names, real merge and rebase conflicts, reflog, snapshots, discard, unstage, rewind, revert, clone, commit, worktree, tags, cherry-pick, lease rejection and deterministic bisect. The snapshot commands were also executed in actual Windows PowerShell and Git Bash. @@ -42,7 +44,7 @@ npm run build:check npm run build ``` -Build-only minifiers are locked in `package-lock.json`; they are not browser dependencies. The build embeds the same `recovery.js` consumed by the interface and tests into `dist/index.html`. The Pages workflow runs `npm test` before building and deploying. +Build-only minifiers are locked in `package-lock.json`; they are not browser dependencies. The build embeds the same `recovery.js` and `learning.js` consumed by the interface and tests into `dist/index.html`. Metadata records base Git HEAD, clean/dirty working-tree state, and a SHA-256 of source/build inputs so an uncommitted artifact is not mistaken for a clean revision. The Pages workflow runs `npm test` before building and deploying. ## Browser verification @@ -54,7 +56,9 @@ node tests/test-browser.cjs Set `GITUNSTUCK_TEST_URL` to test an HTTP deployment or the built `dist/index.html` file URL. Results and screenshots are written to ignored `artifacts/`. -Desktop (1440×1000) and mobile (390×844) Chromium checks cover recovery, staging lessons, command search, reload/Back, retained deep links, copy output, keyboard entry/arrow navigation, focus visibility, reduced motion, sampled recovery-text contrast in both themes, and horizontal overflow. Screenshots were visually inspected. The same journeys passed against the deployed HTTPS site; see [release evidence](docs/recovery-audit/release.md). This is not a complete accessibility certification or cross-browser test. +Current source and built Chromium journeys cover all lessons, reference return/reload/Back/Forward, recovery, legacy routes, clipboard success/failure, input privacy and reference printing. Presentation checks use 320, 390, 768 and 1440 CSS-pixel widths in both themes, keyboard focus, reduced motion, sampled text/graph contrast and desktop CSS zoom at 200%. Screenshots were inspected. Actual browser-menu zoom, a second engine and a real screen-reader pass remain unverified. No accessibility certification or beginner teaching-effectiveness claim is made. + +The new course has not been deployed or tested with actual beginners. See [learning evidence](docs/learning-evidence.md) for the tested scope and remaining gaps. [Earlier release evidence](docs/recovery-audit/release.md) concerns the earlier recovery release, not this learning implementation. ## Limits and evidence diff --git a/docs/learning-evidence.md b/docs/learning-evidence.md new file mode 100644 index 0000000..6062dc5 --- /dev/null +++ b/docs/learning-evidence.md @@ -0,0 +1,274 @@ +# Learning implementation evidence + +Goal: implement docs/learning-implementation.md. Started 6 November 2026. + +## Baseline and scope + +- Revision: 7115b5d643bb1b6259aa13b2b615d07e1d8a0327; branch feat/learning-course. Matches the reviewed baseline. +- Existing user work: untracked docs/GITUNSTUCK_LEARNING_IMPLEMENTATION_PLAN.md; preserved verbatim. Canonical execution copy: docs/learning-implementation.md. +- No applicable AGENTS.md found in checkout or parent directories. CONTRIBUTING.md applies: static architecture, no new dependencies, privacy, accessible controls, checked destructive guidance. User authorization covers local implementation; no issue posting, commits, PR, merge or deployment performed. +- Source map: index.html contains destinations, CSS, router, lessons, graphs and metadata; recovery.js is shared recovery data/logic; scripts/build.mjs embeds recovery.js; tests/test-analyzer.js and tests/test-recovery.js are npm test; tests/test-browser.cjs is optional Playwright QA. Both workflows run Ubuntu with Node 22. +- Existing observations remain: four lesson links, predefined zones/graphs, misleading metadata labels and universal 41-byte claim, quiz says staging moves edits. Source can open directly; production embeds shared code. +- Boundaries: six core lessons (inspect, staging, history, branches, remotes, recovery), optional setup, shared plain-text practice project, complete staging first. Keep recovery.js untouched unless narrow integration or demonstrated correction requires it. Preserve Git 2.23+ syntax, privacy, runtime dependencies and existing build architecture. +- Preserve #terminalAnalyzer, #troubleshootConsole, #undo-lost-reflog, #card-detached, #forge-PROVIDER/INCIDENT, #zone-staging, analogy anchors, search/filter and print. New validated route: #learn/LESSON/CHECKPOINT. +- Available environment: Windows PowerShell, Node v26.12.1, Git 2.56.0.windows.4. Git 2.23, actual beginner sessions, screen reader and second browser remain unverified. + +## Task tracker + +| Task ID | Status | Implementation revision | Checks and result | Evidence location or gap | Next action | +| --- | --- | --- | --- | --- | --- | +| P0.1 | PASS | 7115b5d + working tree | Checkout, instructions, source/build/tests/workflows inspected | Inspect the actual checkout | P0.2 | +| P0.2 | PASS | 7115b5d + working tree | Chromium baseline screenshots and representative journeys | Record representative starting journeys | See task evidence below | +| P0.3 | PASS | 7115b5d + working tree | npm test, build:check, browser: exit 0 | Run and classify existing checks | See task evidence below | +| P0.4 | PASS | 7115b5d + working tree | 45 task IDs and scope/route matrix recorded | Lock the scope and comparison criteria | See task evidence below | +| P1.1 | PASS | 7115b5d + working tree | 194 assertions; rendered staging and editorial review | Make staging explanations consistent | See task evidence below | +| P1.2 | PASS | 7115b5d + working tree | Five graph representation checks; detached image reviewed | Label diagrams and metadata honestly | See task evidence below | +| P1.3 | PASS | 7115b5d + working tree | Content diff and preserved advanced routes reviewed | Reduce competing terminology | See task evidence below | +| P1.4 | PASS | 7115b5d + working tree | Official claim/source map; staging local citations | Tie claims to useful sources | See task evidence below | +| P2.1 | PASS | 7115b5d + working tree | Node import/schema/routes/transitions; canonical fixture | Define canonical lesson and example data | See task evidence below | +| P2.2 | PASS | 7115b5d + working tree | Deep link, reload, Back/Forward and invalid routes in Chromium | Implement a small routing contract | See task evidence below | +| P2.3 | PASS | 7115b5d + working tree | Staging renderer/prediction/reset/browser journey | Render one minimal lesson shell | See task evidence below | +| P2.4 | PASS | 7115b5d + working tree | npm test, build and source/built parity pass | Integrate the shared module with build and tests | See task evidence below | +| P3.1 | PASS | 7115b5d + working tree | Published setup executed in PowerShell 5.1 and Git Bash | Create a reproducible staging practice setup | See task evidence below | +| P3.2 | PASS | 7115b5d + working tree | Five actual HEAD/index/disk/status/diff checkpoints | Implement all five staging checkpoints | See task evidence below | +| P3.3 | PASS | 7115b5d + working tree | All choices, reveal, retry and retained route checked | Add a meaningful prediction and feedback | See task evidence below | +| P3.4 | PASS | 7115b5d + working tree | Actual selected version/file commit; excluded checklist asserted | Add an independent transfer task | See task evidence below | +| P3.5 | PASS | 7115b5d + working tree | Source/built end-to-end; desktop/mobile screenshots | Check the whole lesson before expanding | See task evidence below | +| P4.1 | PASS | 7115b5d + working tree | Both themes reviewed; text contrast min 5.24 light/7.39 dark | Establish a restrained visual system | See P4 evidence below | +| P4.2 | PASS | 7115b5d + working tree | 320/390/768/1440 reflow, outline and expanded answers pass | Add the lesson outline and responsive reading layout | See P4 evidence below | +| P4.3 | PASS | 7115b5d + working tree | Real-Git diff excerpts, exact copy, failure/focus fallback pass | Improve command, output, and diff presentation | See P4 evidence below | +| P4.4 | PASS | 7115b5d + working tree | Keyboard next, named links, reset, reload/Back/Forward pass | Make movement through lessons predictable | See P4 evidence below | +| P4.5 | PASS | 7115b5d + working tree | Keyboard/focus/header/motion/44px controls; screen reader unavailable | Refine interactions and accessible semantics | See P4 evidence below | +| P4.6 | PASS | 7115b5d + working tree | Four representative theme/size images visually reviewed | Apply a deliberate visual review | See P4 evidence below | +| P5.1 | PASS | 7115b5d + working tree | Real Git, PowerShell 5.1/Git Bash setup and browser journey pass | Optional setup reuses practiceSetup; details below | P5.2 | +| P5.2 | PASS | 7115b5d + working tree | Actual tracked/untracked/ignored/index outcomes and browser journey pass | Independent mixed state and wrong restaging checked | P5.3 | +| P5.3 | PASS | 7115b5d + working tree | Full snapshots, focused paths, messages/parents and independent outcome pass | Source/built browser plus real Git | P5.4 | +| P5.4 | PASS | 7115b5d + working tree | Ten real Git checkpoints, exact refs/parents, abort and dirty-switch checks pass | Source/built browser, visual review and full npm suite pass | P5.5 | +| P5.5 | PASS | 7115b5d + working tree | Three-repository states, fetch invariance, independent task and divergence guard pass | Source/built browser and both actual shell setups pass | P5.6 | +| P5.6 | PASS | 7115b5d + working tree | Seven real Git checkpoints, transfer, canonical consequences and both shells pass | Source/built course browser and recovery visual checks | P6.1 | +| P6.1 | PASS | 7115b5d + working tree | Five canonical staging snapshots in existing zones; next/previous/reset and keyboard pass | Make the staging illustration follow real transitions | See P6 evidence below | +| P6.2 | PASS | 7115b5d + working tree | Before/after DAG nodes, parent arrows and refs match actual Git fixtures | Add before/after branch and merge views | See P6 evidence below | +| P6.3 | PASS | 7115b5d + working tree | Two-copy/server text comparison follows actual publication/fetch states | Add a compact remote comparison | See P6 evidence below | +| P6.4 | PASS | 7115b5d + working tree | Optional metadata disclosure; all scenario ID formats and detached agreement pass | Finish the example metadata disclosure | See P6 evidence below | +| P7.1 | PASS | 7115b5d + working tree | Validated return survives reload/search/Back/Forward | Final P7/P8 evidence below | P7.2 | +| P7.2 | PASS | 7115b5d + working tree | Relevant unstage/detached/sync teaching links exercised | Canonical recovery definitions unchanged | P7.3 | +| P7.3 | PASS | 7115b5d + working tree | Legacy routes, analyzer, filters, copy and print pass | Source and built final browser runs | P8 | +| P8.1 | PASS | 7115b5d + working tree | Section 10 outcome matrix passes | Final verification matrix below | P8.2 | +| P8.2 | PASS | 7115b5d + working tree | Source and built journeys exit 0; fingerprint checked | browser-source-final.json / browser-built-final.json | P8.3 | +| P8.3 | PASS | 7115b5d + working tree | Available viewport/theme/keyboard/motion/contrast checks pass | Explicit unavailable-environment gaps below | P8.4 | +| P8.4 | PASS | 7115b5d + working tree | Content corrections and final images reviewed | Itemised quality audit below; no known implementation defect | P8.5 | +| P8.5 | PASS | 7115b5d + working tree | npm ci/test, build:check/build and diff check exit 0 | Final terminal results below; no dependency/privacy scope expansion | Review-ready engineering | +| P9.1 | HUMAN_PENDING | 7115b5d + working tree | No actual participants available | Need 3–5 willing beginners; no fabricated sessions | Observe staging/branch/remote transfer | +| P9.2 | HUMAN_PENDING | 7115b5d + working tree | Depends on actual P9.1 observations | No demonstrated learner findings to address yet | Map findings to fixes and fresh tasks | +| P9.3 | PASS | 7115b5d + working tree | README/CONTRIBUTING updated; historical notices added | Reviewable local patch; description below | User review | +| P9.4 | OPEN | 7115b5d + working tree | No release authorization; no deployment attempted | Local production artifact tested, live verification pending | Authorized release and live smoke test | + +## Executed checks + +- npm run build:check: exit 0; baseline artifact minifies successfully. +- npm test: exit 0; 194 analyzer assertions and 33 recovery scenarios passed, including actual Bash and Windows PowerShell quoted-command scenarios. +- node tests/test-browser.cjs: initial module-resolution failure resolved using the existing installed module/browser paths; see Phase 0 and later source/built evidence. + +## Decisions and gaps + +- Browser baseline must precede UI edits; retain screenshots under ignored artifacts/. +- All real learner evidence remains HUMAN_PENDING when Phase 9 is reached; do not substitute simulated beginners. Deployment requires separate authorization. + +## Phase 0 evidence + +- P0.2: node artifacts/capture-learning-baseline.cjs exited 0. Chromium 151.0.7922.34. Screenshots artifacts/before-{desktop,mobile}-{light,dark}-{fix,learn,reference}.png and before-{desktop,mobile}-graph.png. Inspected mobile light Learn and desktop graph images: readable existing cards, repeated introductory hierarchy; graph anchor heading partly under sticky header; metadata falsely labelled live/actual. These are observations, not a claim that the full interface was reviewed. +- Staging recipe route #analogy-staging → #card-stage; browser Back restores #analogy-staging at desktop/mobile. No explicit exact-checkpoint return exists. Recorded in artifacts/learning-baseline.json. +- P0.3: node tests/test-browser.cjs exited 0 with PLAYWRIGHT_MODULE=D:/GitHub/terraformunstuck/node_modules/playwright/node_modules/playwright-core and CHROMIUM_PATH=C:/Users/dazzo/AppData/Local/ms-playwright/chromium-1234/chrome-win64/chrome.exe. Desktop 1440×1000/mobile 390×844: no page errors, overflow or sampled recovery contrast failures; keyboard focus and legacy routes passed. artifacts/browser-results.json. No new dependency. Windows PowerShell version 5.1.26100.9711. npm ci not rerun because installed locked build tools successfully executed; clean-install verification remains for final checks. +- P0.4: all 45 IDs tracked above; scope and route criteria recorded in baseline. Next bounded task P1.1. + +## P1.1 staging accuracy + +Learner difficulty: saving, staging and committing are confused, and a cart can imply files move away from disk. Changed primer, zone description and quiz feedback to describe copying current content to the index, later independent working edits, and committing the index. Existing graph subtitle and fourZoneData already distinguish saving/staging/committing and remain in place. Real-Git five-checkpoint assertions were added and passed in P3.2; no sentence-matching test added. + +## Phase 1 checkpoint + +- Task: P1.1. Changed: index.html primer/zone/quiz distinguish working content, staged content and commits. Verified: node tests/test-analyzer.js (194/194), browser render and editorial audit. Still unverified: five-checkpoint Git fixture planned for P3.2. Next: P1.2. +- Task: P1.2. Changed: example metadata labels, storage explanation, valid 40-hex illustrative SHA-1 values, detached HEAD arrow directly to c2, main retained at c3, branch note matches graph main at c3. Verified: node artifacts/check-teaching.cjs (exit 0, five scenarios; initially caught 41-character IDs, corrected); visually inspected artifacts/after-teaching-detached.png. Still unverified: fixture graph relationships reserved for P6; invented IDs are not actual Git objects. Next: P1.3. +- Task: P1.3. Changed: remotes introduction explains another repository and fetch/push, keeps pipelines in reference; zone labels use Git terms; removes vault/cart/camera shifts and rebase superiority wording in core explanations. Verified: diff review, preserved advanced cards/routes. Existing browser suite passed after teaching changes. Still unverified: remaining graph prose will be consolidated with real before/after scenarios in P6. Next: P1.4. +- Checks: node tests/test-browser.cjs initially failed existing focus-outline assertion at line 73; unchanged rerun passed both viewports with solid focus outlines and no page errors. Recorded as intermittent, not suppressed or weakened. npm run build:check after final terminology changes: exit 0. git diff --check: exit 0. No recovery.js changes or new dependencies. + +## Official documentation checked on 6 November 2026 + +| Claim | Official source | Implementation/evidence | +| --- | --- | --- | +| add records current content for next commit; later edits need staging again | https://git-scm.com/docs/git-add | P1.1; P3 fixture pending | +| diff compares working/index; --staged compares index/HEAD | https://git-scm.com/docs/git-diff | Existing guidance; P3 fixture pending | +| HEAD may be symbolic or detached | https://git-scm.com/docs/git-symbolic-ref | P1.2 detached illustration | +| References and storage representations | https://git-scm.com/docs/gitrepository-layout and https://git-scm.com/docs/git-update-ref | P1.2 local citation; packed refs/backend caveat | +| Merge preserves parent relationships; rebase replays commits | https://git-scm.com/docs/git-merge and https://git-scm.com/docs/git-rebase | P1.3 removes preference claim; P6 fixtures pending | + +Next bounded task: P1.4 complete the lesson claim/source map and useful local citations, then P2.1 shared canonical lesson model. Goal remains active. + +## P1.4 claim/source map + +| Lesson | Behavioural claims and official documentation | +| --- | --- | +| Setup | Local configuration and identity: git-config (to be checked while completing P5.1); do not present modern test runs as Git 2.23 proof | +| Inspect | Tracked/index/working and untracked observations: https://git-scm.com/docs/git-status; comparisons: https://git-scm.com/docs/git-diff | +| Staging | Current content is added to index: https://git-scm.com/docs/git-add; index is committed: https://git-scm.com/docs/git-commit | +| History | Recorded snapshot and commit metadata: https://git-scm.com/docs/git-commit | +| Branches | References/HEAD: git-symbolic-ref and gitrepository-layout; merge parents: https://git-scm.com/docs/git-merge | +| Remotes | Fetch and remote-tracking observations: https://git-scm.com/docs/git-fetch | +| Recovery | Working/index restoration: https://git-scm.com/docs/git-restore; inverse commit: https://git-scm.com/docs/git-revert | + +The status/commit/fetch/restore/revert manuals were opened in this continuation. The new lesson links to add/diff/commit/status locally. Other lessons must include their relevant citations as added in P5. Displayed status is labelled illustrative; path/hash/summary variability explained. These sources do not replace executable evidence. + +## P2: shared learning foundation + +- Task P2.1: learning.js is a browser/Node module with no DOM, credentials, command execution or learner input. Canonical staging actions use explicit Git argv and exact editor writes; states declare HEAD/index/working/branch/status, initial/final state, prerequisites, feedback, transfer answer and reference. node tests/test-learning.js verifies unknown IDs, duplicate lessons, missing outcome/reference, invalid routes and pure transition isolation. Other lessons deliberately wait for the finished staging pattern. +- Task P2.2: index.html handles #learn and validated #learn/LESSON/CHECKPOINT in the existing router. Invalid IDs offer the outline without echoing input. Native links and history share that path. Browser checks cover deep entry, reload, Back/Forward, extra path segments and encoded invalid input. Existing reference search/filter and legacy journeys retained. +- Task P2.3: renderer supplies outcome, prerequisites, exact setup, editor/command/observation distinctions, index/HEAD/working comparison, prediction, transfer disclosure and named movement. Native controls; role=status for feedback; no completion score. CSS is a minimal reading layout; refinement remains P4. +- Task P2.4: build embeds the same learning.js alongside recovery.js; npm test includes tests/test-learning.js. npm test exit 0: 194 analyzer assertions, 33 recovery scenarios, learning data and Git fixtures. npm run build exit 0. Extended node tests/test-browser.cjs passed source and dist at 1440/390 with canonical data parity and no page errors. Build:check passed before shared module; rerun scheduled after this integrated milestone. +- Routing correction: removed two competing startup timers. Render the initial undo solution at end of synchronous setup, then apply the saved route once. The 120ms route timer could steal focus from a keyboard interaction; simply removing it exposed the earlier 0ms default-render overwrite of a recovery deep link. Both ordering problems corrected, existing checks retained. A fake-DOM analyzer run initially found an unguarded learning container listener; guarded it consistently with optional existing DOM elements. + +## P3: complete staging lesson + +- P3.1: exact published Bash and PowerShell 5.1 setup ran in real shells from isolated temporary parents. Explicit main branch, local example identity, editor-created plain text, no real remote/account. Fixtures isolate global config. P5.1 subsequently isolated inherited signing/hooks/pager settings locally in each fresh practice repository, with an explicit explanation; wider settings remain unchanged. Git 2.23 runtime compatibility remains unverified. +- P3.2: node tests/test-learning.js executes canonical actions and checks actual HEAD/index/file contents, porcelain columns, parent relation, diffs and precise tracked paths for all five checkpoints. Final Version 3 remains uncommitted. +- P3.3: browser journey exercises v1/v2/v3 reasoning, reveal/retry, accessible status and unchanged checkpoint. No inferred mastery. +- P3.4: executable independent task commits Tuesday while Wednesday stays on disk; checklist remains untracked, absent from commit/index and ordinary diff. Worked answer preserves action order and includes verification commands. +- P3.5: source/built browser journeys traverse checkpoints, copy exact commands, reset illustration, reveal transfer and reach reference. Baseline regression paths preserved. Exact explicit lesson/checkpoint return from a reloaded reference remains P7.1; browser Back works, so this unfinished integration is not hidden. +- Visual evidence: node artifacts/check-learning-layout.cjs exit 0; artifacts/staging-{320,390,768,1440}-{light,dark}.png and staging-layout.json. No page horizontal overflow at eight combinations. Inspected 390 light and 1440 dark full-page screenshots: readable comparison and controls, a stale introductory sentence above the lesson and redundant edit instruction to refine in P4. Full-page sticky header capture crosses the desktop image; inspect viewport captures for focused-element occlusion in P4. + +Next task P4.1: refine staging hierarchy/styles and verify contrast, then finish the P4 layout/interaction checks before adding other lessons. Remaining full-course work, actual learner validation and deployment are not complete. + +Staging milestone final verification: extended browser suite (including reference reload and browser Back) exited 0 for both source and built artifact. Separate results retained at artifacts/browser-source-staging.json and artifacts/browser-built-staging.json. npm run build:check and git diff --check exited 0. Next remains P4.1; goal active. + +## P4: staging visual and interaction pattern + +Task P4.1 / Changed: existing theme tokens, restrained spacing, 780px reading column, legible code, strong labelled controls; no new assets/packages. Verified: rendered light/dark lesson screenshots; sampled text minimum 5.24:1 light and 7.39:1 dark; primary control borders and keyboard outlines at least 3:1. Hover/focus/error states checked in both themes. Still unverified: full accessibility conformance is not established by this sample. Next: P4.2. + +Task P4.2 / Changed: desktop checkpoint outline and single-column narrow layout, local scroll for wide comparisons, clearer course introduction and supplemental concept links. Verified: 320/390/768/1440 widths, both themes, long commands and expanded transfer answer, no page overflow. artifacts/learning-presentation.json and staging-layout.json; screenshots staging-WIDTH-THEME.png. Still unverified: second browser engine not installed (only Chromium present). Next: P4.3. + +Task P4.3 / Changed: exact labelled diff excerpts show HEAD → index and index → working content; use -/+ symbols, explain omitted Git headers. Commands copy separately from output. Copy failure announces manual selection/copy and restores focus; temporary fallback textarea is removed even on exceptions. Verified: node tests/test-learning.js compares every displayed excerpt or empty comparison with real Git; browser checks exact copied content, multiline preservation and forced clipboard/fallback failure. Still unverified: OS clipboard integration beyond the controlled browser API. Next: P4.4. + +Task P4.4 / Changed: retained named previous/next checkpoint links, position, current-step semantics and explicit browser restart. Verified: keyboard-only next, all route/history/reload/reset cases, no completion claims. Next: P4.5. + +Task P4.5 / Changed: 44px primary targets, native fieldset/legend/buttons/details, status feedback, focus offsets. Verified: Tab/Enter navigates prediction and next checkpoint at all widths; visible outlines, reduced motion, heading/control visibility below actual header bounds. Found 768px sticky header taller than old 110px offset and corrected offset below 900px. CSS zoom 200% on desktop passes; 320px unzoomed reflow passes. Initial test applied CSS zoom2 to an already 320px viewport (effective 160px) and overflowed; corrected the matrix to distinguish required narrow reflow from desktop enlargement, without claiming that 160px is supported. Still unverified: actual browser-UI zoom and real screen-reader session; CSS zoom is only a reflow probe. Next: P4.6. + +Task P4.6 / Changed: removed stale introduction on lesson routes, replaced repeated edit prose with a file-content label, separated output/diff excerpts, restrained reading width. Verified: visually inspected 390 light/dark and 1440 light/dark viewport images. Existing design, logo and local fonts retained. No brittle existing assertions were weakened. Still unverified: real beginner evaluation remains P9.1. Next: P5.1 optional setup, reusing canonical setup actions. + +Checks at P4: node tests/test-learning.js and node tests/test-analyzer.js exit 0; extended node tests/test-browser.cjs exit 0, including eight viewport/theme contrast cases, control state contrast, keyboard, forced copy failure and desktop CSS enlargement. Full source/built regression will be repeated after integrated course changes. P4 available-environment gate passed with the named external/environment gaps. + +P5.1 / Changed: optional setup lesson reuses practiceSetup and the same Git actions as staging. All direct-entry setups now check Git availability, parent outside an existing repository, printed location and local identity before committing. Expected non-repository preflight error is explained separately. Missing Git/identity guidance and official init/config/rev-parse citations added. Verified: node tests/test-learning.js checks fresh/initialized preflight, local identity, no global identity write, exact snapshot and read-only independent task; both published setup variants execute in actual PowerShell 5.1 and Git Bash. Source browser suite passes optional entry, snapshot, answer and next lesson plus all P4 checks. Still unverified: older Git runtime and external accessibility checks as previously recorded. Next: P5.2. + +P5.2 / Changed: fresh gitunstuck-inspect setup with tracked notes/.gitignore, ignored scratch.txt and later untracked checklist. Predict selected path, interpret both porcelain columns, ordinary diff limits, and clean-status/remote-state limits. Independent task leaves staged/unstaged notes plus untracked checklist and ignored scratch. Verified: node tests/test-learning.js checks every file/index/commit/status, ignored marker, no remote, unchanged HEAD, untracked omissions and wrong restaging outcome. Source Chromium journey and canonical data parity pass; prediction feedback checks added for all choices. Shared setup renderer now lists every exact setup file. Official gitignore manual checked. Next: P5.3. + +## P5.3 and integrated course checkpoint + +Task: P5.3. Changed: history lesson in gitunstuck-history, with two tracked plain-text files, one focused time commit, complete-snapshot prediction and an independent checklist commit leaving a later time edit unstaged. Unchanged tracked checklist content remains in the commit; commit message conventions are not Git requirements. Official show/log manuals checked and cited. + +Verified: node tests/test-learning.js asserts actual complete commit trees, file/index/disk contents, changed paths, parent identities, messages, empty staged diff, remaining working diff and no publishing remote. The independent changed path is checklist.txt while notes.txt remains a later working edit. All four published setup variants executed in actual Windows PowerShell 5.1 and Git Bash. Schema checks now reject unknown sources, missing independent outcomes and duplicate checkpoints. + +Setup isolation refinement: practiceSetup omits imported template hooks via a per-init option and sets signing=false, the fresh repository’s hooks path and a plain pager locally. A fixture supplies failing inherited/template hooks, unavailable signing/pager programs and a different default branch; the authored setup still creates the correct main snapshot and leaves the inherited config byte-for-byte unchanged. This supersedes the initial P3 stop-on-inherited-protection limitation. These settings are explicitly scoped to fresh disposable practice directories. + +Renderer preserves action order, including alternating editor and Git actions. Shared setup lists every declared file. Scrolling comparisons have a named region and a small-screen keyboard/sideways-scroll hint. The 320px inspector comparison is checked for local keyboard scrolling; the page itself stays within the viewport. Copy fallback removes its temporary textarea and returns focus even on exceptions. + +Visual inspection: artifacts/inspect-320-checkpoint.png and history-1440-checkpoint.png reviewed after disabling screenshot transition capture. Readable action/output/observation distinctions and locally scrollable long comparison confirmed. Initial quick screenshots caught theme transition mid-frame and screenshot auto-scroll under the header; recaptured with reduced motion and explicit checkpoint heading scroll. No synthetic screenshot was presented as learner evidence. + +Integrated checks: npm test exit 0 (194 analyzer assertions, 33 recovery scenarios, all current learning fixtures); npm run build and npm run build:check exit 0; git diff --check exit 0. Extended source and built Chromium runs cover all four current lessons, feedback choices, disclosures, routes, copy, legacy capabilities and P4 presentation matrix. Separate browser-source-p5-partial.json/browser-built-p5-partial.json under artifacts/ retain target-specific results. + +Still unverified: Git 2.23 runtime, actual browser-menu zoom, second engine, screen reader and real beginner sessions. Explicit reference return remains P7.1. Next bounded task: P5.4 branches/merges/conflict, followed by remotes and recovery. P5 and the overall goal remain incomplete and active. No commit, PR, merge or deployment performed. + +P5.4 / Changed: ten-checkpoint branch lesson, fast-forward, non-overlapping diverged merge, deliberate same-line conflict, explicit base/ours/theirs index state, chosen resolution and independent library branch. Symbolic b0-b8 labels distinguish commit identities from object IDs. Alternative abort keeps stop/check/consequence/source next to its command and reuses the canonical merge recovery limitation. The teaching commit -m completes the pending merge with an explicit message; the difference from recovery merge --continue is explained. No recovery.js change. Verified: node tests/test-learning.js passes all file/index/status/ref states, all nine commit parent/message relationships, no invented fast-forward commit, unresolved commit refusal, correct resolution, staging-marker limitation, clean-start abort, dirty carry and refused overwrite. Both actual shells execute branch setup. Source browser tests pass every checkpoint, refs, conflict display, feedback, abort copy, reload/reset and transfer. Visually inspected branches-320-checkpoint.png and branches-1440-checkpoint.png: local table scrolling retains three versions without page overflow; compact ref labels remain readable. Official merge/switch/ls-files manuals checked. Still unverified: older Git and external accessibility gaps; built parity will run with the integrated next lesson. Next: P5.5. + +P5.5 / Changed: a fresh gitunstuck-remotes workspace contains learner, partner and shared.git. Canonical setup publishes the initial snapshot and clones a partner copy, with local example identities. All later commands use explicit git -C context and editor labels name the target copy. Five checkpoints distinguish partner commit, publication, stale learner origin/main, fetch and checked fast-forward. A compact text comparison shows both copies and the bare example server; the note comparison explicitly names learner/notes.txt. No hosted login is needed. Provider-specific limits remain explicit. + +Verified: node tests/test-learning.js checks branch tips, remote-tracking tips, index/file contents and status in both copies, plus independent bare-server refs/committed content after every worked checkpoint and independent publication/fetch/integration. Both fetches leave actual learner HEAD, index, working content and status unchanged. The independent fast-forward ends with three real commits, with expected parent relationships and no invented merge. An additional divergent state makes --ff-only refuse while preserving learner state and server tip. The actual published workspace setup runs in Windows PowerShell 5.1 and Git Bash. Only controlled typed action arrays run; repository targets are checked to remain under the disposable workspace. + +Browser and visual evidence: extended node tests/test-browser.cjs passed source and dist for every new branch and remote checkpoint, reference labels, conflict base/ours/theirs, prediction choices, abort copy, git -C fetch copy, transfer answers, reload/reset, old help/reference journeys and the eight P4 viewport/theme combinations. Target-specific results are artifacts/browser-source-branches-remotes.json and browser-built-branches-remotes.json. Visually inspected branches-320-checkpoint.png, branches-1440-checkpoint.png, remotes-320-checkpoint.png and remotes-1440-checkpoint.png. Mobile comparisons stack or scroll locally; no page overflow. Official fetch/push/clone/remote manuals checked and cited. + +Integrated milestone: npm test exited 0 (194 existing analyzer assertions, 33 existing recovery scenarios, all current learning fixtures and twelve shell setup runs); npm run build:check, npm run build and git diff --check exited 0. recovery.js and package dependencies remain unchanged. The earlier P5.4 built-parity follow-up is now satisfied. Still unverified: Git 2.23 runtime, second browser engine, real screen-reader/browser-menu zoom checks and real beginners, as recorded above. Exact reference return remains P7.1. Next bounded task P5.6: choose among unstage, discard and revert using isolated practice states and canonical recovery prerequisites/consequences. The complete course, later visual/navigation integration, final audit and release are not yet complete. Goal stays active; no project commit, PR, merge or deployment performed. + +P5.6 / Changed: recovery lesson distinguishes unstaging from discarding one working file and reverting a checked commit. Canonical recovery.js checks, risks, effects and sources appear before the operation; fixture-specific stop conditions remain visible. Checklist comparison demonstrates discard uses the index, which differs from HEAD, while preserving the wanted notes edit. The clean revert case targets the inspected non-merge parent and uses --no-edit only to accept the default message. A new mixed-state transfer asks for a justified choice and preserves current disk content. Verified: node tests/test-learning.js passes seven actual file/index/status/history checkpoints, unchanged wanted notes, staged-index discard source, four-commit retained history, parent relationships, and an incorrect discard choice in a disposable fixture. Published setup executes in both actual shells. Source/built browser suites pass every recovery checkpoint, all choices, canonical consequence text, prerequisite ordering, selected-file copy and answer. Course sequence now contains optional setup plus all six required lessons. Inspected recovery-1440-checkpoint.png; 320/1440 overflow checks pass. Official restore/revert manuals checked. Evidence files browser-source-course.json and browser-built-course.json retain targets. Next P6.1. Phase 5 engineering gate passes; compatibility, external accessibility and actual learner evidence limits remain explicit. + +## P6 visual explanations + +Task P6.1 / Changed: existing four-zone widget now uses the canonical five-checkpoint staging experiment. Working/index/HEAD notes show separate contents simultaneously; the remote is explicitly unused. Named native checkpoint selector, previous/next/restart, exact practice link, statuses and relevant operation details agree. Operation-type tabs no longer claim to advance a simulated file journey. Verified: browser compares every rendered snapshot/status context with shared definitions, goes backward/forward/reset and operates the select by keyboard; the definitions already passed real Git fixtures. staging-widget-390.png/staging-widget-1440.png retained; desktop visually inspected. Corrected scroll offsets so focused example controls and old visual anchors clear the sticky header. Still unverified: external accessibility gaps below. Next P6.2. + +Task P6.2 / Changed: branch checkpoints render initial or before/after SVG graphs using the existing graph styles. HEAD, every reference, visible reachable commits and child-to-parent arrows come from canonical data; no future resolution commit appears while paused. Current tips start in view; wide histories scroll locally, with a native text-parent disclosure. Existing standalone rebase/detached diagrams remain reachable, with a direct course comparison link. Removed an unsupported never-lose-your-spot reassurance and a universal branch-workflow instruction. Verified: graph nodes/edges and parent order are compared with actual Git object relationships at every branch checkpoint; browser checks rendered edges, reachable node count, current tip visibility and arrow direction. Reviewed branch-comparison-1440-light.png and branch-comparison-390-dark.png. At all eight viewport/theme combinations sampled graph text minimum is 17.06:1 light/18.30:1 dark; meaningful marks minimum 5.48:1 light/6.43:1 dark. No certification inferred. Next P6.3. + +Task P6.3 / Changed: retained the canonical compact remote comparison delivered in P5.5 rather than creating a duplicate. It shows local main, each copy’s observed origin/main and shared main separately, stacks on small screens and has direct text equivalents. Verified: every worked checkpoint and independent publication/fetch/integration matches three actual repositories; browser checks each displayed reference, stale observation, fetched observation and unchanged learner file versions. The display explicitly says illustration, not live connection. No network animation or hosted-state claim. Next P6.4. + +Task P6.4 / Changed: existing metadata inspector is now optional native details/summary. Invented SHA-1 values are scoped to the standalone diagram, separately from course labels; packed/other storage and hash-format caveats remain. HEAD terminology now scopes the loose-reference example. Improved old node/edge contrast using existing theme tokens. Verified: browser opens disclosure by keyboard, visits all five standalone scenarios, checks 40-hex values/symbolic HEAD shape, and confirms detached HEAD/c2 diagram has three commits with main retained at c3. Existing source assertions retained. Next P7.1. + +Integrated checks: npm test exited 0 with 194 analyzer assertions, 33 recovery scenarios, all seven lesson fixtures, graph/Git parent checks and fourteen actual shell setup runs. npm run build:check, npm run build and git diff --check exited 0. Extended source/built Chromium journeys passed; separate results artifacts/browser-source-visuals.json and browser-built-visuals.json. Each includes both existing desktop/mobile journeys and the eight presentation combinations. Source/built canonical lesson equality is asserted. No runtime dependency or recovery.js modification. + +Still unverified: Git 2.23 runtime, second browser engine, real screen-reader session, actual browser-menu zoom and actual beginner transfer. CSS zoom/reflow and native keyboard tests are narrower evidence. Next bounded task P7.1 exact validated lesson/checkpoint return paths through reference reload and history. Remaining P7/P8/P9 work is not complete; goal stays active. + +P6 final route regression: a final keyboard run exposed duplicate popstate/hashchange notifications recreating the same lesson and clearing feedback. The router now skips a URL already rendered, while imperative pushState and reference-filter replaceState invalidate that cache. A deterministic duplicate-event test preserves feedback; normal Back/Forward and reference-search journeys remain asserted. The earlier failing final browser run exited 1; after this correction source and built runs both exited 0. No test expectation was weakened. Analyzer assertions were rerun after the route change (194/194). Final available checks and remaining task scope are recorded above. + +## Final P7/P8/P9 audit — 7 November 2026 + +P7.1 / Changed: lesson reference links carry an allowlisted lesson/checkpoint pair; reference offers an explicit exact return. Search/filter updates preserve validated context. Direct reference visits offer a relevant practice link without inventing a previous lesson. Unknown, duplicated or malformed context is rejected; arbitrary query fields are excluded. Verified: pure URL tests and source/built Chromium journeys include reload, search, return, Back/Forward and a same-document sentinel. A test initially captured search before its debounce completed; it now waits for the expected URL before checking history. Still unverified: none for the implemented local routing contract. Next: P7.2. + +P7.2 / Changed: recovery recipes offer relevant practice links after their existing source, using shared mappings. Verified: unstage, detached and sync teaching destinations; canonical recovery data unchanged. P7.3 / Changed: ancestor disclosures open for old deep links; concept illustrations are optional below the course outline. Printing opens visible-destination disclosures and restores their prior state afterward. Verified: legacy hashes, analyzer, reference search/filter, clipboard, recipe sources and printed steps on source/built. Final disclosure testing initially toggled an already-open wrapper closed after a same-document deep link; the test now checks state before opening it. No production assertion was removed or weakened. + +### Section 10 verification matrix + +| Required behaviour | Actual evidence and result | +| --- | --- | +| Initial commit; stage/edit; commit staged version | Real staging HEAD/index/disk contents at all five checkpoints; working Version 3 survives committing Version 2: PASS | +| Selected-file commit; diff; untracked | Independent staging/history tasks inspect committed paths, excluded checklist, both diff directions and untracked status/diff distinction: PASS | +| Branch create/switch; fast-forward; diverged merge | Actual symbolic HEAD, refs and parent lists at all ten checkpoints; dirty changes carry where allowed and overwrite refusal preserves content; FF creates no commit: PASS | +| Conflict and detached HEAD | Deliberate conflict/unmerged index, resolved content and parents, abort and marker-staging negative case; detached standalone HEAD/ref/node agreement: PASS | +| Two-copy remote; fetch | Learner, partner and bare-server refs checked separately; stale observation demonstrated; fetch leaves learner HEAD/index/disk unchanged; divergence refuses FF: PASS | +| Unstage; discard; revert | Actual disk/index preservation, index-sourced replacement of only unwanted edit, inverse commit with original ancestors and wanted content retained: PASS | +| Routes and context return | Deep/reload/Back/Forward/unknown routes, duplicate browser events, exact reference return, malformed context and search preservation: PASS | +| Privacy | Terminal sentinel absent from URLs, observed requests, console and local/session storage; no new persistence or transmission: PASS | +| Rendering and copy | Source/built canonical data equality; exact clipboard command, rejection fallback/manual-copy announcement, cleanup and retained focus: PASS | +| Accessible use | Available environment matrix below: PASS within tested scope | +| Existing capability | 194 analyzer assertions, 33 recovery scenarios; browser analyzer, recovery, filters, legacy hashes and reference print: PASS | + +### Available browser and visual checks + +Windows, Chromium 151.0.7922.34, existing Playwright installation; source and built file URLs. Desktop 1440×1000 and mobile 390×844 exercise all lessons and existing destinations. Presentation matrix covers 320/390/768/1440 CSS px in light/dark themes, staging comparisons and branch graphs. No page overflow, page exceptions or console errors. Sampled lesson text minimum contrast 5.24 light / 7.39 dark; graph text 17.06 / 18.30 and meaningful marks 5.48 / 6.43. Keyboard navigation, visible focus, feedback announcements, 44px primary controls, reduced motion, clipboard errors, expanded transfer answers and desktop CSS zoom 2 passed. These checks do not establish full accessibility conformance. + +Inspected final staging feedback at 390 dark, branch comparison at 1440 light and reference print preview, alongside the earlier theme/size/widget/remote/recovery images. Parent arrows and reference labels agree with fixtures; long comparisons scroll locally. The course outline leads directly to exercises; older explanations sit in an optional native disclosure. Final print preview includes recipe commands that were previously hidden in closed details; PDF saved locally. Source/built results are separately retained at ignored artifacts/browser-source-final.json and artifacts/browser-built-final.json; screenshots and reference-print.pdf are also local artifacts, not committed evidence bundles. + +P8.4 quality corrections: staged copies versus moving files; editor save versus commit; clearly invented metadata; exact branch starting commit; branch creation separated from later commits; fast-forward separated from new merge commits; identical overlapping edits need not conflict; detached HEAD descriptions preserve needed work rather than promise safety; repeated lesson introductions hidden; advanced illustration controls disclosed on request. No known unresolved factual, navigation or visual defect identified by this review. This is implementation/self-review, not beginner evaluation. + +Unavailable checks remain explicit: actual Git 2.23 runtime, second browser engine, real screen reader and actual browser-menu zoom. Git 2.23-compatible command syntax is not a verified old-runtime claim. Native keyboard/CSS zoom checks are narrower evidence. Actual beginner effectiveness remains HUMAN_PENDING. + +### Build identity and review preparation + +Base HEAD is still 7115b5d643bb1b6259aa13b2b615d07e1d8a0327 on feat/learning-course; changes are uncommitted. Final tested build records dirty working tree and source SHA-256 dc861e22fc5ff33fdd53469fe10778fa0b67ac75a93b6a3d53fb63c743aa12bc. The built browser test independently recomputes it from exact source/build inputs. Documentation/test-only edits do not change that fingerprint. npm ci completed successfully using the existing lockfile; npm run build:check and npm run build exited 0. Artifact is 378.5 KB minified / 82.5 KB Brotli. No runtime dependency, lockfile, recovery.js or workflow change. Final test terminal result is recorded below when available. + +P9.3 review description: GitUnstuck previously offered concept illustrations without a complete practice sequence. The change adds optional setup and six linked lessons with executable practice states, predictions, independent tasks and reference returns. A learner can stage Version 2, edit Version 3, predict the next commit, and verify that Version 2 was committed while Version 3 remains on disk. Branch and remote diagrams now follow checked repository states. Shared definitions drive the source, self-contained build and real-Git outcome tests. README and CONTRIBUTING explain usage, authoring, environment scope and evidence limits; older proposal documents are labelled historical. Local branch/patch is reviewable; no PR was requested or opened. + +P9.1/P9.2 remain HUMAN_PENDING: recruit 3–5 willing beginners for staging/branch/remote tasks, record anonymous task outcomes and assistance/misconceptions, then fix demonstrated issues and observe changed transfer tasks. No participants or observations have been invented. P9.4 remains OPEN pending release authorization: no commit, push, merge or deployment performed. A future authorized release must verify deployed revision/fingerprint, staging, recipe return and legacy recovery, and record its actual rollback revision/process. Phase 9 is not complete. + +Final terminal results: npm test exited 0 after the integrated source changes: 194/194 analyzer assertions, 33/33 recovery scenarios, all seven lesson fixtures and independent outcomes, exact graph/remote relationships, negative states, inherited-config isolation and fourteen published setup executions (seven lessons × PowerShell 5.1/Git Bash). Source and built browser suites both exited 0. npm ci, build:check, build and final git diff --check exited 0; line-ending notices only. The canonical plan compares equal to the original supplied plan. All 45 task IDs are accounted for: 42 PASS, two HUMAN_PENDING, one OPEN for unauthorized release. Implementation and available validation are complete; human validation and release are separate pending states. No known remaining engineering task within the authorized objective. + +## Ready-to-run beginner sessions + +Prepared after implementation; no session has occurred. P9.1 and P9.2 remain HUMAN_PENDING. Use 3–5 willing Git beginners, anonymous IDs B1–B5, the same tested source or built artifact, and fresh lesson practice directories. Do not use participants' own projects. Record browser/OS/Git versions and which artifact they used. Explain that the interface is being evaluated; the participant can stop at any time. Do not record names, credentials or unrelated terminal content. + +Let each participant work through the relevant lesson, then attempt its independent task with the worked answer closed. Ask them to predict the result aloud before changing repository state. They may consult the lesson or reference; record that use. Do not supply command names. If they request help, first ask what they expect to change; record any further hint or demonstrated command and whether it enabled completion. + +| Task | Participant prompt | Facilitator checks after the attempt | +| --- | --- | --- | +| Staging | Save a Tuesday meeting note, select it for the next commit, then save a Wednesday revision. Add a new checklist. Record only the selected Tuesday note. Predict what will remain afterward. | Committed note is Tuesday; disk note is Wednesday; checklist is untracked and absent from the commit. Ask why saving Wednesday did not replace the selected version. | +| Branches | From the lesson's clean resolved state, create a branch for changing the meeting location to the library. Record the change there, return to main, and integrate it by fast-forward. Predict the branch tips and number of new commits. | Both tips reach the location commit; integration adds no extra commit; file content is correct. Ask whether creating a branch alone isolates uncommitted edits. | +| Remotes | In the partner copy, record and publish a Thursday meeting change. Predict all three relevant branch observations in the learner copy and shared repository. Retrieve the update, inspect the learner file before integration, then integrate appropriately. | Server and partner advance first; learner origin/main remains stale until fetch; learner main/file remain unchanged by fetch; integration updates them. Ask which operation first changed the learner file. | + +These prompts match the existing tested independent tasks. Facilitator expectations are not participant instructions; avoid revealing them before the attempt. Use actual file/index/ref observations to distinguish a correct explanation from an accidentally successful command sequence. Stop on an unexpected repository state and preserve the anonymous finding rather than improvising destructive recovery. + +For each participant/task, fill this record only after an actual observation: + +| Participant/task | Prediction and explanation | Actual repository outcome | Lesson/reference/answer consulted | Assistance supplied | Hesitation or misconception | Proposed correction and fresh-task result | +| --- | --- | --- | --- | --- | --- | --- | +| Not yet observed | — | — | — | — | — | — | + +Report independent completion, assisted completion or incomplete separately. No timing, success rate or quote exists until observed. For P9.2, map each serious observed problem to a specific correction and regression check; then use a fresh task with changed note/location details to check the affected concept. Record the real result and any assistance. A participant repeating the original worked answer does not establish transfer. Keep learner findings separate from the existing automated passes and do not change task status merely because this protocol is ready. + +## Draft PR preparation + +The user subsequently authorized opening a draft PR, including the necessary feature-branch commit and push. Earlier statements that no commit/PR was authorized describe the implementation checkpoint at that time. Remote main still matches baseline 7115b5d643bb1b6259aa13b2b615d07e1d8a0327. Publish the reviewed implementation and canonical plan/evidence on feat/learning-course; leave the original user-supplied untracked plan untouched. Real learner checks remain HUMAN_PENDING and release remains unauthorized. The PR description carries final commit identity and validation scope; the local dirty-build fingerprint above remains historical test evidence, not a claim about a deployed revision. + +The first staged diff check, which includes newly tracked files, flagged the supplied plan's Markdown hard-break whitespace and extra final blank line. The canonical execution copy now removes that whitespace for publication; its wording is unchanged. The original supplied file remains untouched and untracked. Earlier exact-equality/diff-check statements describe the implementation checkpoint before publication normalization. No runtime input changed during PR preparation. diff --git a/docs/learning-implementation.md b/docs/learning-implementation.md new file mode 100644 index 0000000..8920fe4 --- /dev/null +++ b/docs/learning-implementation.md @@ -0,0 +1,893 @@ +# GitUnstuck learning improvement plan + +Version 1.0 · 6 November 2026 +Purpose: implementation instructions for an LLM, with reviewable tasks and evidence requirements. +Repository: https://github.com/dazzo31/gitunstuck +Reviewed baseline: 7115b5d643bb1b6259aa13b2b615d07e1d8a0327, committed 3 November 2026. +Scope of this document: a plan. Its preparation did not modify the repository or execute its tests. + +## 1. Intended result + +GitUnstuck should help someone inspect a repository, choose what to commit, work on a branch, exchange work, and recover from common mistakes. A learner should be able to explain the result of a command and perform a similar task without copying the example. + +Keep the three existing destinations: Fix a problem, Learn Git, and Find a command. Give Learn Git a coherent course with practical exercises and a clear route back from reference material. Improve the appearance through readable typography, spacing, restrained colour, and useful diagrams. + +Success is demonstrated by correct repository outcomes, usable navigation, readable interfaces, and observed learner performance. Text volume, feature counts, screenshots alone, and passing source-string assertions do not demonstrate teaching quality. + +### Delivery boundaries + +Included: + +- Six core lessons and one optional setup lesson. +- One consistent plain-text practice project. +- A complete staging exercise delivered before the remaining lessons. +- Better before/after teaching in the existing visual tools. +- A compact remote example with two working copies and a shared repository. +- Navigation between lessons, reference entries, and recovery explanations. +- Responsive presentation, accessible controls, accurate terminology, and meaningful checks. +- Executable Git fixtures and browser journeys for the new learning behaviour. +- Honest documentation of tested environments and remaining gaps. + +Excluded from this implementation: + +- AI tutors, chat interfaces, generated answers, accounts, analytics, advertising, certificates, points, streaks, leaderboards, achievement badges, and completion scores. +- New frontend frameworks, runtime packages, remote fonts, icon libraries, or image dependencies. +- A browser terminal that interprets arbitrary commands, or a Git implementation in WebAssembly. +- A new landing-page campaign, giant hero area, decorative dashboard, invented usage statistics, or extensive logo redesign. +- A complete GitHub/GitLab/Bitbucket or CI/CD course. Existing reference material remains available. +- A general rewrite of the analyzer, recovery engine, build system, or entire repository. +- A general collection of advanced Git topics beyond the existing material. +- Collecting a learner's repository, terminal contents, credentials, or personal information. + +The new course is bounded. New topics require a specific unmet learning need, a place in the sequence, and a corresponding exercise. Record future ideas separately; do not implement them during these tasks. + +## 2. Verified starting point + +These are observations from the reviewed revision, not promises about the execution checkout. + +| Area | Observed baseline | Implication | +| --- | --- | --- | +| Main destinations | Fix, learn, and reference already exist | Improve their connections; preserve the navigation model | +| Learn Git | Four topic links, introductory explanations, one knowledge check | Add outcomes, practice, and lesson continuity | +| Four-zone widget | Selects predefined explanations and example statuses | Reuse it as an illustration with explicit state transitions | +| Commit graph | Selects predefined scenarios | Add before/after comparisons without claiming actual repository inspection | +| Metadata inspector | Labels include Actual .git/ Files and LIVE FILE SYSTEM STATE | Replace misleading claims with accurate example labels | +| Staging explanations | Detailed panel says staging copies content; quiz feedback says it moves changes | Correct the inconsistency everywhere it appears | +| Recipe links | A staging lesson link opens the reference destination | Provide an exact return route and preserve lesson context | +| Runtime | index.html, recovery.js, and local SVG assets | Preserve static use and no runtime dependencies | +| Build | Existing build-only minifiers; production embeds recovery.js | Update the current build when introducing learning.js | +| Tests | npm test runs analyzer and recovery tests | Add learning outcomes to the existing test entry point | +| Browser QA | Optional tests/test-browser.cjs; existing Playwright installation | Extend the existing approach without a new test framework | +| CI | Checked-in workflows run on Ubuntu | Do not claim a checked-in Windows CI job exists | +| Older plans | Some describe an earlier monolithic app with no build step | Treat them as historical proposals, not the current architecture | + +No AGENTS.md or Copilot instruction file was present in the upstream tree inspected for this plan. At implementation time, read any applicable instructions in the actual checkout and its parent directories. + +Current source entry points: + +- https://github.com/dazzo31/gitunstuck/blob/7115b5d643bb1b6259aa13b2b615d07e1d8a0327/index.html +- https://github.com/dazzo31/gitunstuck/blob/7115b5d643bb1b6259aa13b2b615d07e1d8a0327/recovery.js +- https://github.com/dazzo31/gitunstuck/blob/7115b5d643bb1b6259aa13b2b615d07e1d8a0327/CONTRIBUTING.md +- https://github.com/dazzo31/gitunstuck/blob/7115b5d643bb1b6259aa13b2b615d07e1d8a0327/README.md +- https://github.com/dazzo31/gitunstuck/blob/7115b5d643bb1b6259aa13b2b615d07e1d8a0327/scripts/build.mjs +- https://github.com/dazzo31/gitunstuck/blob/7115b5d643bb1b6259aa13b2b615d07e1d8a0327/tests/test-browser.cjs + +If HEAD differs, inspect the relevant diff and update the observations and task mapping. Retain completed improvements; do not recreate them because this plan describes an older baseline. + +## 3. Rules that prevent AI slop + +These rules govern decisions and review. Passing a phrase blacklist is insufficient. + +### 3.1 Every addition must earn its place + +Before adding content or a control, state: + +1. The specific learner difficulty. +2. The behaviour or explanation that addresses it. +3. How its value or correctness will be checked. + +If these cannot be stated concretely, omit the addition. Reuse existing material when it already answers the need. + +Examples: + +| Proposed change | Decision | +| --- | --- | +| Show a file edited after staging | Include: explains why committed and working contents can differ | +| Add a decorative animated terminal | Exclude: no learning task depends on it | +| Add a return link from a recipe to the current exercise | Include: prevents loss of lesson context | +| Add a percentage labelled Git mastery | Exclude: reading and clicks do not establish mastery | +| Add a collapsed explanation of why an answer was wrong | Include when it addresses a named misconception | +| Repeat the same introductory paragraph in every panel | Remove duplication; use local context and a useful link | + +### 3.2 Editorial rules + +- Explain the Git term first. Use a short analogy only when it clarifies a specific point. +- Explain an analogy's limit where it could mislead. Staging does not remove a file from disk. +- Use consistent terms: working directory, index/staging area, commit, branch, HEAD, remote, remote-tracking branch. +- Remove marketing language, generic introductions, invented expertise, unsupported reassurance, and decorative jargon. +- Avoid descriptions such as cloud robots, magical safety, vault protection, messy merges, or guaranteed recovery. +- Each paragraph must explain a concept, action, consequence, diagnostic observation, or limitation. +- Avoid repetitive headings such as What this means followed by a restatement of the title. +- Use meaningful example commit messages; conventional-commit prefixes are optional and must not appear required by Git. +- Show limitations honestly: an example is an example; a self-check is not verified performance in a real repository. +- Do not invent review dates, test results, learner quotes, user counts, measured reading times, or accessibility certification. +- Keep explanations brief enough for the task. Do not pad lessons to reach a length or force every topic into the same number of paragraphs. +- Apply caution where a command needs it. Keep immediate prerequisites visible instead of repeating generic warnings throughout the page. + +### 3.3 Interface rules + +- A visual element must help identify location, action, state, comparison, or consequence. +- Keep decoration subordinate to reading and doing. +- Use the existing logo and local assets. Use exact SVG/code for diagrams. +- Keep a clear distinction between navigation links, action buttons, command blocks, output blocks, and disclosures. +- Every enabled control must do something observable. Explain or remove unavailable actions. +- Do not hide essential exercise steps or command consequences behind several disclosures. +- Do not add extra destinations, modes, settings, or permanent side panels without a demonstrated need. +- Keep reference and recovery details accurate and accessible while the learning interface becomes simpler. + +### 3.4 Definition of an unacceptable change + +Reject a task's implementation if it contains factual ambiguity, duplicated teaching without a distinct purpose, a control with no useful result, unsupported claims of verification, ornamental complexity, or a regression hidden by weakening tests. + +Revise or remove the offending part. Do not describe a stylistic opinion as an automated proof that all AI slop has been eliminated. + +## 4. Implementation contract for the LLM + +### Work one bounded task at a time + +1. Read this plan, applicable checkout instructions, the execution tracker, and the relevant source. +2. Choose the next unblocked task. State its ID and intended observable result. +3. Identify the files and behaviours in scope. +4. Implement the smallest complete change that satisfies that task. +5. Run checks appropriate to the change. Run relevant outcome tests when Git behaviour changes. +6. Inspect the diff and the resulting interface when presentation changes. +7. Record the evidence, remaining gaps, and next task. +8. Continue through authorized work without requesting routine phase-by-phase approval. + +Do not stop after producing a scaffold or describing what could be implemented. Do not let unrelated cleanup consume the implementation. + +### Task status vocabulary + +Use OPEN, ACTIVE, PASS, BLOCKED, or HUMAN_PENDING. + +- PASS requires the task's acceptance conditions and evidence. +- BLOCKED names a concrete missing capability or unresolved dependency. +- HUMAN_PENDING applies only to work requiring actual external learner or user evidence. +- An LLM role-playing a beginner cannot clear HUMAN_PENDING. +- Continue independent tasks when an environment or human-dependent check is unavailable. +- Do not mark a phase complete while one of its required tasks is BLOCKED or HUMAN_PENDING. +- Distinguish implementation complete, automated checks passed, human validation pending, and released. + +### Minimal execution records + +At implementation time, place this plan in docs/learning-implementation.md. Use one additional file, docs/learning-evidence.md, for: + +| Task ID | Status | Implementation revision | Checks and result | Evidence location or gap | Next action | +| --- | --- | --- | --- | --- | --- | + +Include short decision notes in that evidence file. Do not create a collection of overlapping governance documents, handoff templates, and status reports. + +After each task, report: + +~~~text +Task: +Changed: +Verified: +Still unverified: +Next: +~~~ + +A useful checkpoint contains changed files and exact test commands, not a transcript of internal reasoning. + +### Scope and interruption rules + +- Do not edit recovery.js unless a task requires a demonstrated defect correction or a narrow integration hook. +- Do not replace existing tests with weaker assertions to make changed markup pass. +- Do not silently change supported Git versions, privacy behaviour, deployment paths, or old deep links. +- Do not add packages to solve a styling or navigation problem. +- If a task needs broader changes, record the dependency, complete unaffected work, and raise only the concrete unresolved decision. +- Repository contribution procedures should be followed within the actual implementation request's authorization. This plan does not itself authorize posting issues, merging, or deploying. +- Commit, open a PR, merge, and deploy only within the authorization of the eventual execution request. Do not infer release authorization from the existence of Phase 9. +- If work is interrupted, update the tracker with the current revision, incomplete conditions, and the next bounded task. Resume from there. + +## 5. Course and practice specification + +### Core lesson sequence + +| ID | Title | Observable outcome | Required independent task | +| --- | --- | --- | --- | +| setup | Set up a practice repository | Check Git availability, find the practice directory, and set author identity locally if needed | Confirm the directory and identity before starting | +| inspect | Read the repository's state | Explain tracked, untracked, staged, and unstaged observations | Identify which files and contents are eligible for the next commit | +| staging | Choose what goes into a commit | Predict the difference between HEAD, the index, and working files | Stage one change, edit again, and commit only the intended version | +| history | Record and inspect history | Create a focused commit and inspect its snapshot and message | Make a second focused change and verify exactly what was committed | +| branches | Work on a branch and merge | Explain which reference changes and resolve a deliberate simple conflict | Complete a similar branch change with a different line of text | +| remotes | Exchange work with another copy | Distinguish local, remote-tracking, and server branches | Fetch another person's commit, explain the observed references, and integrate appropriately | +| recovery | Choose a recovery action | Distinguish unstaging, discarding an uncommitted edit, and reverting a commit | Choose and justify an action for a fresh scenario | + +Setup is optional. The other six are the core sequence. Preserve direct access for experienced users; do not force everyone through the course. + +### Lesson structure + +Each core lesson contains: + +1. A concrete outcome and prerequisites. +2. A small worked example in the common practice project. +3. A prediction before the important transition. +4. Commands or explicit editor actions. +5. Expected observations, including empty output where relevant. +6. An explanation tied to those observations. +7. A similar independent task with a collapsed worked answer. +8. A link to the relevant reference or recovery entry and a next lesson link. + +The independent task must change some detail from the worked example. Repeating the exact command immediately after seeing it is weak evidence of understanding. + +Use the same plain-text project, such as notes.txt and checklist.txt, across lessons. Avoid language runtimes, package managers, web deployment, and a real hosting account in the core exercises. + +Reuse the same project template and story, while giving each lesson a named fresh practice directory. The remotes lesson has its own shared repository and two copies. This keeps an unfinished edit from one exercise from silently changing a later exercise. Do not add a second continuation mode in this implementation. + +Each lesson definition must declare its initial files, initial index/commit/reference state, prerequisites, and expected final state. Provide a short, tested setup route for direct entry. The expected result must say which changes intentionally remain uncommitted. Never repair an unexpected starting state by automatically resetting or deleting the learner's work; direct them to a fresh practice directory. + +### Practice environment + +- Put all exercises in an explicitly named new practice directory. +- Require the learner to confirm its location before repository-changing commands. +- Use repository-local author configuration; do not change global settings for the course. +- Explain that commits can record the configured author identity and may be published. +- Teach file edits as editor actions. Where shell commands are supplied, provide separately tested Bash and Windows PowerShell 5.1 instructions. +- Avoid Bash-only command chaining, quoting, redirection, or utilities in shared instructions. +- Keep Git command syntax within the existing Git 2.23+ support claim. In particular, do not introduce newer setup flags without checking compatibility. +- Make setup independent of the user's default branch, commit signing settings, hooks, pager, and previously configured remotes. +- Tests isolate configuration in temporary directories; learner instructions explain necessary local configuration without disabling their wider protections. +- Restarting the browser example changes only example state. +- Restarting a local exercise uses a fresh practice directory. Do not offer broad delete/reset commands as a convenience. +- Local remotes use a local bare repository and two working copies. Hosted-provider limitations are explained separately. +- No core exercise asks the user to paste their real terminal output into the site. + +### Canonical staging experiment + +Use the following repository states and verify them with real Git: + +| Checkpoint | Action just taken | HEAD file contents | Index file contents | Working file contents | +| --- | --- | --- | --- | --- | +| initial | Commit Version 1 | Version 1 | Version 1 | Version 1 | +| edited-v2 | Edit to Version 2 | Version 1 | Version 1 | Version 2 | +| staged-v2 | Stage the file | Version 1 | Version 2 | Version 2 | +| edited-v3 | Edit to Version 3 | Version 1 | Version 2 | Version 3 | +| committed-v2 | Commit without staging again | Version 2 | Version 2 | Version 3 | + +Important observations: + +- After edited-v3, the same file has staged and unstaged differences. +- After committed-v2, the committed content is Version 2 and the working file is still Version 3. +- The staged diff is then empty while the working diff remains. +- git diff compares working content with the index by default. +- git diff --staged compares the index with HEAD. +- Untracked files do not appear as ordinary content changes in these diffs until relevant content is added to the index. + +Follow this with an independent task using different text and a second file that must remain outside the commit. + +## 6. Interface specification + +This is a restrained refinement of the existing site. Avoid a fresh visual identity. + +| Element | Required treatment | Acceptance check | +| --- | --- | --- | +| Global navigation | Keep the three named destinations prominent; keep Learn Git one action away from the default view | Labels remain visible and understandable on mobile | +| Learn introduction | One short description and a clear starting action; optional setup link | A first-time learner can identify where to begin | +| Desktop lesson layout | A compact lesson outline beside one readable main column | No competing dashboard panels or excessive card nesting | +| Mobile layout | Single column; lesson outline in an accessible disclosure when space is limited | Reading order matches task order; controls do not obscure content | +| Course position | Current lesson and next action, using names and sequence numbers | No mastery percentage or automatic claims of competence | +| Main column | Target approximately 65–75 characters per line for explanatory prose; allow code/table exceptions | Comfortable reading at desktop and narrow widths | +| Typography | System fonts; body text at least 16 CSS px at default zoom; comfortable line height around 1.5–1.65 | Text remains usable with zoom and user text-spacing overrides | +| Spacing | Small consistent spacing scale; clear separation between explanation, action, and observation | Alignment and grouping survive different text lengths | +| Colour | Retain existing brand colours with neutral surfaces; one principal action treatment | State is never expressed by colour alone | +| Surfaces | Use borders, spacing, and modest radius; avoid nested shadows, frosted glass, and decorative gradients | Commands and observations are visually distinct | +| Lesson controls | Previous, next, show answer, reset example; accurate names for each action | No decorative controls and no ambiguous Continue buttons | +| Commands | Copyable command-only blocks; text labels for Bash/PowerShell where relevant | Clipboard excludes prompt symbols, output, and explanatory prose | +| Output | Labelled expected or example output; preserve meaningful whitespace | Never presented as the learner's live terminal | +| Diffs | Show additions and removals with symbols plus colour; explain what is being compared | Works without colour perception | +| Diagrams | Readable labels and equivalent text; before/after changes identified | Keyboard and screen-reader users can obtain the same explanation | +| Feedback | State what the learner selected, the correct reasoning, and the next useful action | No empty praise or shaming language | +| Technical details | Disclose advanced internals below the core explanation | The lesson remains understandable without opening them | +| Support links | Keep available but visually secondary to lesson work | No competing primary call to action inside exercises | + +Additional checks: + +- Normal text contrast at least 4.5:1. Check both themes and relevant hover, focus, selected, and error states. +- Check meaningful graphical objects and component boundaries against applicable non-text contrast requirements. +- Aim for approximately 44 by 44 CSS px for primary touch controls. This is a design target; WCAG 2.2 AA's target-size criterion has a 24 by 24 CSS px minimum with exceptions. +- Use clear visible focus and ensure sticky headers do not hide focused controls or anchor headings. +- Check 320, 390, 768, and 1440 CSS px widths; check both themes at representative sizes. +- At 200% zoom and narrow reflow, the page must remain usable. Local horizontal scrolling may be necessary for code or a data table; the page itself should not scroll sideways. +- Respect reduced motion. No essential information may depend on animation, hover, or drag. +- Prefer native links, buttons, details/summary, and form controls. Add ARIA for a demonstrated semantic need. +- A lesson step advances only through an explicit learner action. Clicking a topic or reference link does not mark learning complete. +- Preserve the existing default destination unless a separately justified task changes it. Do not force an interstitial choice screen before urgent recovery help. + +## 7. Architecture and file boundaries + +Use the existing static architecture. A small shared learning module is justified so lesson data, example transitions, and executable checks can agree. + +| File | Intended responsibility | +| --- | --- | +| index.html | Existing markup/styles/navigation; lesson renderer and accessible UI | +| learning.js, new | Canonical lesson IDs, examples, action definitions, and pure example-state transitions; importable in browser and Node | +| recovery.js | Existing canonical recovery recipes and analyzer; normally unchanged | +| tests/test-learning.js, new | Lesson-data validation and real Git exercise outcomes | +| tests/test-browser.cjs | Extended real user journeys, accessibility-related behaviour, and presentation checks | +| tests/test-recovery.js | Existing recovery outcomes; change only for a relevant regression | +| tests/test-analyzer.js | Existing parser/source assertions; adapt narrowly when necessary | +| scripts/build.mjs | Embed learning.js alongside recovery.js in the production artifact | +| package.json | Include learning outcomes in npm test; preserve locked build dependencies | +| README.md and CONTRIBUTING.md | Accurate usage, support, and teaching-content rules | +| docs/learning-implementation.md | This plan | +| docs/learning-evidence.md | Tracker, evidence, design decisions, and unresolved checks | +| .github/workflows/check.yml and deploy.yml | Existing checks; only necessary additions for the new suite | + +Do not split every lesson into a new component or introduce a content framework. + +Keep lesson data and state independent of the DOM. Use explicit known action IDs. A browser action updates an illustrated state; it never executes a command on the user's computer. + +Represent executable Git actions with argument arrays and file-edit actions with exact fixture contents. The test harness must run controlled Git actions directly, without evaluating arbitrary lesson prose or shell command strings. + +Where an exercise uses an existing recovery operation, reference the canonical recipe. Reuse compatible prerequisite/consequence content. A deliberately different teaching action may have its own definition; explain the distinction rather than pretending the commands are interchangeable. + +Prevent HTML injection when rendering labels, messages, code, and unexpected route values. Follow existing escaping patterns. + +Source checkout use must work with the new local module beside index.html. The production HTML must embed the same learning data and transitions that were tested. Document the extra source file honestly. + +## 8. Phase map + +| Phase | Focus | Depends on | Exit condition | +| --- | --- | --- | --- | +| 0 | Baseline and bounded scope | None | Current behaviour and checks are recorded | +| 1 | Teaching accuracy and terminology | 0 | Misleading and inconsistent explanations are corrected | +| 2 | Shared lesson model and routing | 1 | Minimal learning foundation works in source and built output | +| 3 | Complete staging lesson | 2 | One complete exercise is correct, usable, and executable | +| 4 | Clear, attractive learning interface | 3 | The staging lesson establishes the finished visual and navigation pattern | +| 5 | Remaining course lessons | 4 | Optional setup and six core lessons satisfy the common contract | +| 6 | Visual explanation improvements | 3–5 | State transitions, branch comparisons, and remote example agree with Git | +| 7 | Reference and recovery integration | 5–6 | Cross-destination journeys retain context and existing capabilities | +| 8 | Integrated quality verification | 7 | Required executable and browser checks pass; gaps are explicit | +| 9 | Learner evaluation and release readiness | 8 | Actual learner evidence is recorded and the change is reviewable | + +Do not batch a full course rewrite before completing the staging lesson. Fix problems discovered in that first lesson before copying its pattern. + +## 9. Detailed task list + +### Phase 0 — Establish the baseline + +#### P0.1 — Inspect the actual checkout + +Change: read applicable instructions, git status, current HEAD, relevant source, scripts, and workflows. Compare against the reviewed revision if necessary. + +Done when: the evidence file records the actual revision, existing user changes, applicable constraints, and which baseline observations still apply. Work occurs on an isolated branch/worktree when implementation is requested and needed. + +Evidence: revision and concise file/behaviour map. Do not overwrite unrelated user work. + +#### P0.2 — Record representative starting journeys + +Change: inspect Fix, Learn, and Reference at desktop/mobile widths and in both themes. Follow staging to its reference card and back. Inspect the graph, metadata labels, keyboard navigation, and old deep links. + +Done when: the evidence distinguishes observed problems from preferences. Retain a small representative set of before screenshots for comparison. + +Evidence: URLs, viewport/theme labels, screenshots, and brief observations. Avoid collecting a screenshot for every card. + +#### P0.3 — Run and classify existing checks + +Change: run the existing test and build checks, and available browser QA, before implementation. + +Done when: results are recorded as actual runs with environment details. Existing failures are separated from later regressions. Missing tooling is recorded precisely. + +Evidence: exact commands, exit results, Git/Node/browser versions, and a short failure description where needed. Do not copy pass counts from README as current evidence. + +#### P0.4 — Lock the scope and comparison criteria + +Change: create the task tracker and record the course sequence, UI brief, file boundaries, known compatibility requirements, and old routes to preserve. + +Done when: all 45 task IDs are tracked and the next task is clear. Unrelated proposals are outside the implementation. + +Evidence: completed baseline section and tracker. Phase 0 is not an excuse to start a separate architecture project. + +Phase gate: baseline recorded, regressions detectable, scope bounded. + +### Phase 1 — Correct the teaching + +#### P1.1 — Make staging explanations consistent + +Change: audit primer text, quiz feedback, zone descriptions, command examples, and graph explanations for claims that staging moves files or that an editor save creates a commit. + +Done when: each explanation distinguishes current working content, staged content, and committed content. A learner can edit after staging without contradicting the text. + +Evidence: reviewed occurrences and the real-Git staging fixture planned for Phase 3. Avoid source-string tests for every sentence. + +#### P1.2 — Label diagrams and metadata honestly + +Change: replace live/actual inspection claims for predefined data. Remove universal 41-byte and fixed-hash-format claims, or clearly scope an example to its stated representation. + +Done when: each illustration is identified as an example. HEAD, branch labels, displayed hashes, and explanatory text agree, including detached HEAD. The simple example is not presented as a complete account of every Git storage backend. + +Evidence: scenario-by-scenario review against official Git documentation and rendered output. + +#### P1.3 — Reduce competing terminology + +Change: use the agreed Git terms and remove unnecessary metaphor changes. Separate introductory remotes content from pipelines. Remove language suggesting merging is inherently messy or rebasing is inherently preferable. + +Done when: core explanations remain understandable without translating between several analogies. Existing advanced content stays reachable with accurate labels. + +Evidence: concise terminology and content-movement notes. Do not rewrite unrelated pages just to impose a new voice. + +#### P1.4 — Tie claims to useful sources + +Change: map each lesson's important behavioural claims to the relevant official Git documentation. Identify environment-dependent output and illustrative values. + +Done when: citations support the actual claim and sit where useful. Any reviewed date corresponds to work performed. Sources do not substitute for tested exercises. + +Evidence: a compact source map in the evidence file and a content diff free of unsupported claims. + +Phase gate: no known contradictions in the learning explanations being extended. + +### Phase 2 — Add the minimum learning foundation + +#### P2.1 — Define canonical lesson and example data + +Change: introduce learning.js with stable lesson IDs, initial/final state manifests, prerequisites, ordered actions/checkpoints, observations, prediction feedback, independent tasks, solutions, and relevant reference IDs. + +Done when: the module imports in Node without browser globals, contains no credentials or learner input, and exposes testable pure state transitions. Add schema checks only for meaningful requirements. + +Evidence: import/data checks, including unknown IDs, duplicate IDs, missing outcomes, and missing references. + +#### P2.2 — Implement a small routing contract + +Change: support #learn as the course outline and #learn/LESSON/CHECKPOINT as a direct lesson location. Validate every ID. Keep existing hashes and reference-search URL state working. + +Done when: reload, Back, Forward, copied lesson URLs, and unknown lesson/checkpoint values behave predictably. Old hashes resolve to the corresponding material without silently entering the wrong destination. + +Evidence: route matrix and browser assertions. Use one navigation path instead of separate unrelated click handlers. + +#### P2.3 — Render one minimal lesson shell + +Change: render the current lesson, outcome, steps, prediction, observation, answer disclosure, previous/next links, and accessible state messages. + +Done when: a placeholder-free staging draft can be read and navigated using keyboard alone. Explain that example controls change the browser illustration, not a real repository. + +Evidence: a focused browser journey. Do not apply a full site redesign in this task. + +#### P2.4 — Integrate the shared module with build and tests + +Change: embed learning.js in production, add the learning suite to npm test, and compare rendered/source data with the canonical module. + +Done when: source checkout and built output load successfully, with no missing module or duplicate execution. Build checks remain meaningful and require no new dependencies. + +Evidence: npm test, npm run build:check, npm run build, and source/built parity results. + +Phase gate: a working, testable learning foundation without a framework migration. + +### Phase 3 — Deliver the complete staging lesson + +#### P3.1 — Create a reproducible staging practice setup + +Change: define the plain-text project, local identity setup, initial committed Version 1, and separate Bash/PowerShell setup instructions where needed. + +Done when: setup works in a new practice directory and does not depend on a real hosting account or global author settings. Commands respect the Git 2.23+ support boundary. + +Evidence: a real repository fixture plus actual shell validation or an explicit outstanding shell gap. + +#### P3.2 — Implement all five staging checkpoints + +Change: implement the canonical staging experiment from Section 5 with a side-by-side content comparison and relevant status/diff observations. + +Done when: every checkpoint agrees with real Git's HEAD, index, working file, and staged/unstaged differences. Empty output is explained accurately. + +Evidence: assertions on file contents, git show HEAD:path, index content, and diffs. Never infer correctness from command exit codes alone. + +#### P3.3 — Add a meaningful prediction and feedback + +Change: ask which contents will be committed after the second edit. Explain why each plausible incorrect answer is wrong. + +Done when: feedback addresses the selected misconception, preserves the state being discussed, and is announced accessibly. Revealing an answer does not mark the lesson mastered. + +Evidence: correct/incorrect/reveal/retry browser paths and an editorial review. + +#### P3.4 — Add an independent transfer task + +Change: use new text plus a second file that must stay outside the commit. Supply a collapsed answer and an explicit way to inspect the result. + +Done when: the task requires applying the idea with changed details. Its expected result distinguishes the committed contents, remaining work, and excluded file. + +Evidence: executable independent-task fixture and expected result. Do not auto-grade an actual repository the page cannot inspect. + +#### P3.5 — Check the whole lesson before expanding + +Change: run the source and built lesson end to end, including reset example, commands copied, reference entry, and return path where available. + +Done when: no placeholders, contradictory observations, dead controls, or core steps hidden by layout remain. If reference return is unfinished, track that condition against P7.1 explicitly. + +Evidence: focused desktop/mobile review and passing staging outcome tests. + +Phase gate: one complete and accurate practical lesson establishes the teaching pattern. + +### Phase 4 — Make the learning interface clear and attractive + +#### P4.1 — Establish a restrained visual system + +Change: consolidate the necessary learning-view typography, spacing, surfaces, and action styles around existing brand colours. Reuse existing tokens where suitable. + +Done when: the staging lesson has clear hierarchy and comfortable reading in both themes. There are no decorative metric cards, excessive shadows, or nested card shells. + +Evidence: representative before/after screenshots and measured contrast for the relevant text and controls. + +#### P4.2 — Add the lesson outline and responsive reading layout + +Change: use a compact desktop outline and readable main column; adapt to a single-column mobile view. Show lesson names and current location. + +Done when: learners can find the next action without scanning unrelated topics. At 320 CSS px the page does not overflow horizontally; wide code/tables scroll locally when necessary. + +Evidence: screenshots at 320, 390, 768, and 1440 widths, plus overflow checks. + +#### P4.3 — Improve command, output, and diff presentation + +Change: distinguish commands from observations; label shell-specific setup; make copy buttons copy only executable command text. Present the comparison behind each diff. + +Done when: no prompt marker or output is copied accidentally. Important line breaks survive. Differences use symbols as well as colour. Clipboard failure has useful feedback. + +Evidence: clipboard-content assertions, narrow-layout inspection, and rendered diffs matching fixtures. + +#### P4.4 — Make movement through lessons predictable + +Change: supply named previous/next links, checkpoint location, visible reset-example action, and a useful outline on small screens. + +Done when: links navigate and buttons act; browser history and headings agree with the displayed lesson. Reset never implies deletion of local files. + +Evidence: keyboard, Back/Forward, reload, and deep-link journeys. No learning-completion claim is triggered by navigation. + +#### P4.5 — Refine interactions and accessible semantics + +Change: use appropriate native controls, useful accessible names, visible focus, concise announcements, reduced-motion support, and adequate touch targets. + +Done when: the lesson works without hover, dragging, animation, or colour perception. Sticky navigation does not conceal the focused item. + +Evidence: keyboard-only review, focus inspection, reduced-motion checks, and screen-reader check where available. + +#### P4.6 — Apply a deliberate visual review + +Change: inspect the finished staging lesson in both themes and at desktop/mobile sizes. Check alignment, line length, heading order, disclosure density, and long labels. + +Done when: the main explanation, action, observation, and next step are immediately distinguishable. Remove visual elements that compete with those tasks. + +Evidence: a short list of observed issues and their corrections. Replace brittle old exact-colour/radius assertions only with checks that continue protecting intended behaviour and readability. + +Phase gate: the staging lesson is the reference design for all later lessons. + +### Phase 5 — Complete the course content + +#### P5.1 — Add optional setup + +Change: turn the tested P3.1 setup into the optional setup lesson, reusing its canonical actions. Explain Git availability, opening the right directory, local identity, editor use, and safe practice-directory setup. Provide concise troubleshooting for missing Git or author identity; do not maintain a second setup implementation. + +Done when: someone can prepare the common project without starting inside another repository or changing global settings. + +Evidence: tested setup in supported shells; a note of any environment not actually exercised. + +#### P5.2 — Add Read the repository's state + +Change: teach tracked/untracked files and staged/unstaged observations through the common project. Introduce status before commands that change state. + +Done when: the worked example and independent task require interpreting observations. Explain that a clean status has limits, including ignored files and previously observed remote state. + +Evidence: actual tracked/untracked/ignored/index fixture outcomes and checked feedback. + +#### P5.3 — Add Record and inspect history + +Change: teach a focused commit, a meaningful message, and inspecting actual committed contents. Explain that recording locally and publishing are separate actions. + +Done when: the learner can verify which changes entered a commit and which remain outside it. + +Evidence: real commit tree/content assertions and an independent two-file task. Avoid treating commit-message style conventions as Git requirements. + +#### P5.4 — Add Work on a branch and merge + +Change: use consistent commits and branch names to show branch creation, a clean merge, and a deliberate same-line conflict. Explain editing the intended resolution before continuing. + +Done when: branch references and working-file contents agree with the explanation. A conflict is presented as a state to resolve; staging alone does not establish that the resolution is correct. + +Evidence: real fast-forward/non-fast-forward/conflict cases with parent and file-content checks. Include a checked abort explanation using existing recovery guidance where applicable. + +#### P5.5 — Add Exchange work with another copy + +Change: use two working copies and one local bare remote. Demonstrate publishing, another person's commit, stale remote-tracking information, fetch, and an appropriate integration step. + +Done when: the learner can distinguish the local branch, its remote-tracking reference, and the server branch. The core task works without login; provider-specific review requests are separate. + +Evidence: assertions from all three repositories before/after each relevant operation, including a fetch that leaves current working content unchanged. + +#### P5.6 — Add Choose a recovery action + +Change: teach selecting among unstage, discard, and revert using isolated practice states and canonical recovery guidance. Keep prerequisites and consequences immediately available. + +Done when: the independent scenario asks for a justified choice. Discard is explicitly identified as replacing working content; revert is explained as adding a commit rather than deleting history. + +Evidence: actual index/file/history outcomes and links to the matching existing recipes. Do not introduce reset --hard or force-push as beginner shortcuts. + +Phase gate: all six core lessons and optional setup satisfy the lesson contract and have executable outcomes. + +### Phase 6 — Improve the visual explanations + +#### P6.1 — Make the staging illustration follow real transitions + +Change: connect the existing four-zone content to the staging experiment. Display relevant content differences and named checkpoints. + +Done when: stepping backward or forward restores the correct illustration; the index and working file can show different versions simultaneously. It never implies files physically migrate between exclusive locations. + +Evidence: pure transition tests, fixture comparisons, and keyboard-accessible operation. + +#### P6.2 — Add before/after branch and merge views + +Change: reuse existing graphs with explicit initial state, action, and resulting state. Keep HEAD, branch names, parent arrows, and narrative aligned. + +Done when: learners can identify which pointers move and which commits are created. Existing rebase and detached examples remain reachable with accurate scope and prerequisites. + +Evidence: compare graph states with real fixture relationships. Fix misleading branch isolation claims for uncommitted work and any detached graph/text mismatch. + +#### P6.3 — Add a compact remote comparison + +Change: show the two working copies and server in a compact layout. Distinguish observed remote-tracking information from the current server branch, using the remotes lesson's canonical example. + +Done when: another person's push and the learner's fetch visibly change the appropriate references. The example remains readable on mobile and has a text equivalent. + +Evidence: fixture-matched reference states and before/after checks. No animated network activity or fake live server status. + +#### P6.4 — Finish the example metadata disclosure + +Change: label the inspector as example Git metadata. Keep advanced details optional; align its values with the chosen graph/checkpoint. + +Done when: shown hashes or abbreviations are valid for the stated example, and the explanation does not assert that every repository stores refs as individual fixed-length files. Do not imply it reads the user's .git directory. + +Evidence: representation checks, scenario review, and accessibility inspection. + +Phase gate: visual states, text, and executable repository states tell the same story. + +### Phase 7 — Connect learning with help and reference + +#### P7.1 — Implement exact lesson return paths + +Change: lesson links to recipes retain a validated lesson/checkpoint return context. Use explicit allowlisted navigation state, such as learnReturn and learnStep query values, alongside existing reference hashes. + +Done when: a learner can open a recipe, reload it, and return to the exact exercise checkpoint. Opening the reference directly shows a useful related-lesson link instead of an invented Back destination. + +Evidence: browser journeys for return/reload/Back/Forward, invalid context values, and coexistence with reference search/filter URL state. No free-text input goes into the URL. + +#### P7.2 — Add contextual teaching links to recovery + +Change: provide one relevant learning link where a recovery diagnosis or recipe benefits from it. Examples include unstage to staging, detached HEAD to branches, and divergence to remotes. + +Done when: the immediate recovery task remains prominent and operational prerequisites remain intact. Links have specific names explaining the concept available. + +Evidence: a reviewed mapping and a browser sample of each distinct route type. Do not inject a repeated Learn Git banner into every result. + +#### P7.3 — Preserve existing routes and behaviour + +Change: maintain original anchor aliases and reference functionality while obsolete learning presentation is consolidated. + +Done when: legacy analyzer, undo, detached, forge, and zone links still resolve; search/filter sharing and print/reference export remain usable. Pasted output privacy is unchanged. + +Evidence: the route regression matrix, existing tests, and focused print/browser inspection. + +Phase gate: new learning journeys integrate without damaging urgent help or existing links. + +### Phase 8 — Verify the complete change + +#### P8.1 — Execute the learning outcome matrix + +Change: run fixtures for all required lessons and independent tasks through the shared definitions. Assert state, not just success messages. + +Done when: the matrix in Section 10 passes, including both correct transitions and meaningful invalid or incomplete states. + +Evidence: exact commands, environment, and results. Avoid tests that merely repeat the renderer's own calculations as their expected answer. + +#### P8.2 — Check source and production journeys + +Change: run browser journeys against source and the built artifact. Cover course entry, staging, branch comparison, remotes, feedback, clipboard, references, and legacy links. + +Done when: displayed data agrees with canonical definitions; no console errors, broken modules, dead controls, or build-only regressions occur. + +Evidence: separate source and built results. Match any production revision metadata to the actual tested revision. + +#### P8.3 — Check responsiveness and accessibility + +Change: perform the viewport/theme/zoom/keyboard/motion checks in Section 6. Include a second browser engine and a screen-reader pass where available. + +Done when: required available-environment checks pass, with other checks explicitly identified. Do not claim full accessibility conformance from automated contrast sampling. + +Evidence: a compact matrix of tested environment, task, result, and remaining gap. Inspect long output, expanded answers, and error states. + +#### P8.4 — Perform the content and visual quality review + +Change: review each paragraph/control against Section 3. Inspect the rendered interface as well as source. + +Done when: all known misleading claims, redundant introductions, repeated warnings, inconsistent terms, irrelevant controls, and ornamental clutter are resolved. + +Evidence: itemised corrections and a final unresolved-issue list. An LLM self-review is useful but cannot be presented as real beginner evaluation. + +#### P8.5 — Run the full regression and build checks + +Change: run the final required project commands after the integrated changes, then review the diff for accidental scope expansion. + +Done when: relevant existing and new tests pass; build succeeds; no dependencies, privacy changes, or unrelated rewrites have slipped in. + +Evidence: final revision, commands, exit results, and documented limitations. Repeat broader checks only when changes or unresolved failures justify them. + +Phase gate: implementation and available automated/browser validation are complete; remaining external checks are explicit. + +### Phase 9 — Evaluate with learners and prepare release + +#### P9.1 — Observe actual beginners + +Change: ask three to five willing beginners, when available, to attempt representative staging, branch, and remote tasks without being told the commands. Record anonymous task-level observations. + +Done when: actual sessions identify where participants succeed, hesitate, misunderstand, or need help. Participant recruitment and observations must be real. + +Evidence: task, result, assistance needed, misconception, and proposed fix. Mark HUMAN_PENDING if no participants are available. Continue all other release-preparation work. + +#### P9.2 — Address findings and recheck transfer + +Change: fix demonstrated problems within scope and use a similar task with different details to check the affected idea again. + +Done when: each observed serious misconception has a correction and, where possible, a fresh observation. Do not infer general teaching effectiveness from one successful participant. + +Evidence: finding-to-change mapping, relevant regression results, and honest remaining uncertainties. + +#### P9.3 — Prepare accurate project documentation and review + +Change: update README and CONTRIBUTING with the course, source files, supported environments, how to add a lesson, and evidence limits. Prepare a focused change description when a PR is authorized. + +Done when: reviewers can understand the learner problem, resulting behaviour, verification, and outstanding checks without reading the conversation. Old proposal docs are clearly historical where they conflict with current architecture. + +Evidence: final diff and reviewable branch/PR or patch as authorized. Documentation must not claim human validation that remains pending. + +#### P9.4 — Release only when authorized, then verify + +Change: when deployment is authorized, follow the existing release process and test the deployed learning route, staging exercise, recipe return, and legacy recovery link. Check deployed revision metadata. + +Done when: the live artifact matches the intended revision and the sampled journeys work. Record actual results and any remaining human or compatibility limitations. + +Evidence: deployment URL, revision, smoke-test results, and a concrete rollback revision/process. Without release authorization, leave the completed change reviewable and state that deployment is pending. + +Phase gate: review-ready, implementation-validated, learner-validated, and released are reported as separate states. + +## 10. Required verification matrix + +| Behaviour | Required evidence | +| --- | --- | +| Initial commit | HEAD/index/working content agree | +| Stage then edit again | Index retains staged version; working file differs; both status categories are explainable | +| Commit after second edit | Commit contains the index version; later working edit remains | +| Selected-file commit | Unrelated file stays outside the commit | +| Diff interpretation | Working/index and index/HEAD comparisons show the expected content | +| Untracked file | Status detects it; ordinary diff does not misrepresent it as tracked content | +| Branch creation and switch | Correct reference/HEAD state; uncommitted work is not falsely described as isolated | +| Fast-forward merge | Expected reference advances; no fabricated merge commit | +| Diverged merge | Parent relationships and resulting file contents match the example | +| Conflict resolution | Deliberate conflict occurs; intended resolved content is committed | +| Detached HEAD example | HEAD/graph/reference descriptions agree | +| Two-copy remote workflow | Local, remote-tracking, and server branch tips are checked independently | +| Fetch | Appropriate observations update; current working content remains as expected | +| Unstage | Disk contents remain; intended index content changes | +| Discard in practice repo | Only the intended working edit is replaced; consequence is explicit | +| Revert | An inverse commit is added and original history remains reachable | +| Routes | Deep link/reload/Back/Forward/invalid-ID behaviour works | +| Context return | Exact lesson/checkpoint survives reference reload | +| Privacy | No learner/free-text terminal content is added to URLs, network requests, logs, or storage | +| Rendering | Source and built UI agree with canonical learning and recovery definitions | +| Copy | Clipboard contains the displayed command only; fallback feedback works | +| Accessible use | Keyboard/focus/announcements/motion/contrast/reflow checks have recorded results | +| Existing capability | Analyzer, recovery, reference search/filter, legacy links, and print remain usable | + +Testing requirements: + +- Reuse the existing temporary-repository approach and Node assertions. +- Keep fixture repositories and configuration disposable and isolated from personal/global state. +- Validate file and index contents and commit relationships rather than fixed commit IDs or version-dependent output prose. +- Normalise non-essential output differences; retain differences essential to the lesson. +- Treat captured displayed output as illustrative and explain variable paths, hashes, branch names, and messages. +- Do not execute arbitrary user-provided commands or parse lesson prose as executable code. +- Do not add snapshot tests for every paragraph, colour, or margin. +- Preserve existing recovery evidence and distinguish local Git results from hosted-provider behaviour. +- Test Bash and Windows PowerShell 5.1 setup instructions in their actual shells. A JavaScript fixture running Git does not prove shell quoting works. +- Verify the Git 2.23 claim in a suitable environment or record that compatibility check as outstanding. Running only a newer Git version is insufficient evidence for every older-version claim. + +Existing commands, to be run separately as appropriate: + +~~~text +npm ci +npm test +npm run build:check +npm run build +node tests/test-browser.cjs +~~~ + +Browser QA currently uses an existing Playwright installation. Set PLAYWRIGHT_MODULE and CHROMIUM_PATH only to actual installed paths when required. GITUNSTUCK_TEST_URL selects the target. Run against both source and the actual built artifact; do not invent npm scripts or claim browser tests are part of npm test unless you implement that change deliberately. + +## 11. Completion and review gates + +Implementation is complete only when: + +- All required lesson content and independent tasks are present and correct. +- The staging experiment demonstrates the five specified states. +- Visualisations and example metadata agree with repository outcomes. +- The learning interface meets the clarity and responsive requirements. +- Reference and recovery links preserve context and old URLs still work. +- The source and production artifact use the same tested learning definitions. +- Existing recovery behaviour and input privacy remain intact. +- Relevant tests pass and unavailable environment checks are explicit. +- No placeholder content, fabricated evidence, unnecessary dependencies, or unexplained scope changes remain. + +Human validation is complete only when actual learner evidence has been collected and reviewed. Deployment is complete only after an authorized release and live verification. + +An unfinished human check must not erase completed engineering work or stop independent preparation. It must remain visible in the final status. + +### Review questions + +1. Can the learner explain which content the next commit will record? +2. Can they demonstrate that staging and saving in an editor are different? +3. Can they distinguish a local branch, a remote-tracking reference, and a branch on the server? +4. Does each command include enough context to avoid applying it to the wrong state? +5. Does each diagram show exactly the behaviour its text describes? +6. Can the learner find the next step and return from reference material? +7. Is any paragraph or visual element present mainly to make the site appear larger or more sophisticated? +8. Are claims of testing, accessibility, compatibility, or teaching effectiveness supported by actual evidence? + +Any unanswered factual or navigation issue is a defect to address. Aesthetic preferences should be resolved consistently within the interface brief. + +## 12. Kickoff instruction for the implementing LLM + +Copy this instruction into the implementation session alongside this document: + +~~~text +Implement the GitUnstuck learning improvement plan in the attached document. + +Start with P0.1. Inspect the actual repository and applicable instructions. +Use the plan's task IDs, dependencies, file boundaries, and evidence rules. +Complete one bounded task at a time and continue through authorized work. +Deliver the complete staging lesson before expanding the other lessons. +Keep the existing recovery and command-reference capabilities working. + +Use the existing static architecture and tests. Introduce only the small +shared learning module and checks specified by the plan. Do not add runtime +dependencies, an AI tutor, accounts, gamification, analytics, decorative +dashboards, or unrelated features. + +For each task, implement the behaviour, verify the outcome, inspect the diff, +update docs/learning-evidence.md, and report: +Task / Changed / Verified / Still unverified / Next. + +An addition must address a specific learner difficulty and have a meaningful +check. Remove filler, duplicated explanations, misleading simulation labels, +unsupported safety claims, and ornamental complexity. + +Never fabricate tests, screenshots, learner research, compatibility evidence, +or review dates. Real beginner sessions require real people. Mark that work +HUMAN_PENDING if unavailable and continue independent engineering work. + +Do not repeatedly ask for approval of routine implementation choices. +Do not merge or deploy unless the actual execution request authorizes it. +At completion, distinguish implementation, automated/browser validation, +human validation, and release status. +~~~ + +## 13. Source references + +Git behaviour: + +- Recording changes and the staged/unstaged distinction: https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository +- git add: https://git-scm.com/docs/git-add +- git diff: https://git-scm.com/docs/git-diff +- Git references and HEAD: https://git-scm.com/book/en/v2/Git-Internals-Git-References +- Remote-tracking branches and fetch: https://git-scm.com/book/en/v2/Git-Branching-Remote-Branches + +Interface criteria: + +- WCAG contrast explanation: https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html +- WCAG target-size explanation and exceptions: https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html + +Consult the relevant official command manual while implementing additional operations. Record the documentation actually checked and the repository outcomes actually executed. This source list is a starting map, not evidence that every eventual statement has been reviewed. diff --git a/docs/v3-feature-plan.md b/docs/v3-feature-plan.md index afac549..7143344 100644 --- a/docs/v3-feature-plan.md +++ b/docs/v3-feature-plan.md @@ -1,5 +1,7 @@ # GitUnstuck v3 — Feature Plan +Historical proposal. Its architecture/status statements describe an earlier checkout. Use README.md, CONTRIBUTING.md and learning-implementation.md for the current learning work; this file is retained for context. + > Branch: `v3` (off `main` @ `v2.2.1` / `0cda374`) > Source of inspiration: Terraform Unstuck's recipe safety model (`docs/SAFETY_MODEL.md`, per-recipe "When to stop", source citations with review dates, and read-only "Check first" separation). > Status: Phase 1 in progress. diff --git a/docs/v3.1-content-plan.md b/docs/v3.1-content-plan.md index 7b171aa..c951c76 100644 --- a/docs/v3.1-content-plan.md +++ b/docs/v3.1-content-plan.md @@ -1,5 +1,7 @@ # GitUnstuck v3.1 — Content Additions Plan (for LLM review) +Historical proposal. Its architecture/status statements describe an earlier checkout. Current learning scope and evidence are in learning-implementation.md and learning-evidence.md. + > Status: **PROPOSAL — for review before implementation** > Branch target: `v3.1` (off `main` @ `v3.0.0` / `92d1226`) > Scope: enrich existing recipe cards with recovery knowledge gaps, with all diff --git a/index.html b/index.html index f1f53e3..e75614a 100644 --- a/index.html +++ b/index.html @@ -1036,8 +1036,8 @@ } /* SVG Theme Adaptive Classes */ - .node-circle-base { fill: #151f32; stroke: #334155; stroke-width: 3; } - [data-theme="light"] .node-circle-base { fill: #ffffff; stroke: #94a3b8; } + .node-circle-base { fill: var(--bg-card); stroke: var(--text-muted); stroke-width: 3; } + [data-theme="light"] .node-circle-base { fill: #ffffff; stroke: var(--text-muted); } .node-text-title { font-family: var(--font-mono); font-size: 12px; font-weight: bold; fill: #f8fafc; } [data-theme="light"] .node-text-title { fill: #0f172a; } @@ -1045,8 +1045,8 @@ .node-text-desc { font-size: 11px; fill: #94a3b8; font-weight: 500; } [data-theme="light"] .node-text-desc { fill: #334155; } - .graph-edge-base { stroke: #334155; stroke-width: 2.5; } - [data-theme="light"] .graph-edge-base { stroke: #94a3b8; } + .graph-edge-base { stroke: var(--text-muted); stroke-width: 2.5; } + [data-theme="light"] .graph-edge-base { stroke: var(--text-muted); } .graph-hint-text { font-size: 11px; font-style: italic; fill: #94a3b8; } [data-theme="light"] .graph-hint-text { fill: #475569; } @@ -2151,6 +2151,80 @@ .secondary-path, .symptom-details, .sample-details { margin: 18px 0; } summary { cursor: pointer; padding: 8px 0; } .learning-path { line-height: 2; padding-left: 24px; } + #learn.lesson-open > .learning-path, #learn.lesson-open > .hero-primer, + #learn.lesson-open > #learningIllustrations, + #learn.lesson-open > .learn-introduction, #learn.lesson-open > .concept-links-label, + #learn.lesson-open #fourZoneModel, #learn.lesson-open #commitGraphExplorer { display: none !important; } + #learningCourse { margin: 24px 0; min-width: 0; } + #learningIllustrations > summary { cursor: pointer; min-height: 44px; padding: 12px 0; border-top: 1px solid var(--border); font-weight: 600; } + .course-list { padding-left: 24px; } + .course-list a { font-weight: 700; color: var(--accent-green); } + .course-list p { margin: 6px 0 16px; } + .lesson-layout { display: grid; grid-template-columns: 220px minmax(0, 1fr); gap: 32px; } + .lesson-reading { min-width: 0; max-width: 780px; line-height: 1.65; } + .lesson-reading h3 { font-size: 1.65rem; } + .lesson-reading h4 { font-size: 1.15rem; margin: 18px 0 10px; } + .lesson-reading p { margin: 12px 0; } + .lesson-reading a, .lesson-outline a, .lesson-movement a { color: var(--accent-green); text-underline-offset: 3px; } + .lesson-outline ol { padding-left: 22px; } + .lesson-outline li { padding: 6px 0; } + .lesson-outline a { display: inline-block; padding: 6px 0; } + .lesson-outline [aria-current="step"] { font-weight: 700; text-decoration-thickness: 3px; } + .learning-example-note { border-left: 3px solid var(--accent-green); padding-left: 14px; } + .learning-setup { border-block: 1px solid var(--border); padding: 16px 0; margin: 22px 0; } + .lesson-reading summary { cursor: pointer; font-weight: 600; min-height: 36px; } + .learning-table-scroll { overflow-x: auto; margin: 20px 0; } + .learning-table-help { display: none; } + .learning-comparison { border-collapse: collapse; width: 100%; } + .learning-comparison th, .learning-comparison td { padding: 12px; text-align: left; border: 1px solid var(--border); } + .learning-comparison caption { text-align: left; padding-bottom: 8px; font-weight: 600; } + .learning-comparison pre { margin: 0; } + .learning-output { padding: 14px; border: 1px solid var(--border); background: var(--bg-card); overflow-x: auto; white-space: pre; } + .learning-output-label { font-weight: 600; } + .lesson-reading pre, .lesson-reading pre code { font-size: 0.9rem; line-height: 1.6; } + .lesson-reading .snippet-header { color: var(--text-muted); } + .lesson-reading .copy-btn { min-width: 44px; min-height: 44px; border-color: var(--text-muted); } + .learning-diffs { display: grid; grid-template-columns: repeat(2,minmax(0,1fr)); gap: 16px; } + .learning-diffs figure { margin: 0; min-width: 0; } + .learning-diffs figcaption { font-size: 0.9rem; } + .learning-diffs .learning-output { margin-top: 8px; } + .learning-ref-list, .graph-reference-list { display: flex; flex-wrap: wrap; gap: 12px 24px; padding-bottom: 12px; } + .learning-ref-list > div, .graph-reference-list > div { display: flex; gap: 10px; align-items: baseline; } + .learning-ref-list dt { font-weight: 600; } + .learning-alternative { margin: 20px 0; border-block: 1px solid var(--border); padding: 12px 0; } + .learning-recovery-gate { border-left: 3px solid var(--text-muted); padding-left: 16px; margin: 20px 0; } + .learning-recovery-gate[data-learning-recipe="discard"] { border-color: var(--accent-red); } + .zone-example-controls { display: flex; flex-wrap: wrap; gap: 10px; align-items: center; margin: 18px 0; } + .zone-example-controls :is(button,select) { font: inherit; color: var(--text); background: var(--bg-card); border: 1px solid var(--text-muted); border-radius: 6px; min-height: 44px; padding: 8px; max-width: 100%; } + .zone-example-controls button:disabled { opacity: .55; cursor: default; } + .zone-example-content { white-space: pre-wrap; overflow-wrap: anywhere; padding: 10px; background: var(--bg-code); color: var(--text); border: 1px solid var(--border); margin: 8px 0; } + #fourZoneModel, #commitGraphExplorer, .zone-example-controls :is(button,select) { scroll-margin-top: 110px; } + @media (max-width: 900px) { #fourZoneModel, #commitGraphExplorer, .zone-example-controls :is(button,select) { scroll-margin-top: 180px; } } + .learning-remote-comparison { margin: 20px 0; } + .learning-graph-pair { display: grid; grid-template-columns: repeat(2,minmax(0,1fr)); gap: 18px; margin: 20px 0; } + .learning-graph-figure { min-width: 0; margin: 16px 0; } + .learning-graph-figure figcaption { font-weight: 700; } + .learning-graph-scroll { overflow-x: auto; margin: 12px 0; } + .learning-graph-svg { display: block; min-width: 0; max-width: none; height: 230px; } + summary.git-internals-header { cursor: pointer; min-height: 44px; } + @media (max-width: 768px) { .learning-graph-pair { grid-template-columns: minmax(0,1fr); } } + .learning-remote-comparison figcaption { font-weight: 600; } + .learning-remote-grid { display: grid; grid-template-columns: repeat(3,minmax(0,1fr)); gap: 16px; margin-top: 12px; } + .learning-remote-grid > div { border-top: 2px solid var(--text-muted); padding-top: 10px; min-width: 0; } + .learning-remote-grid h5 { font-size: 1rem; } + .learning-remote-grid code { overflow-wrap: anywhere; } + @media (max-width: 768px) { .learning-remote-grid { grid-template-columns: minmax(0,1fr); } } + .lesson-reading .snippet-block { min-width: 0; margin: 16px 0; } + .lesson-reading .code-content { overflow-x: auto; } + .learning-prediction { border: 1px solid var(--border); padding: 16px; margin: 22px 0; } + .learning-prediction button, .lesson-movement button { font: inherit; color: var(--text); background: var(--bg-card); border: 1px solid var(--text-muted); padding: 8px 12px; border-radius: 6px; min-height: 44px; cursor: pointer; margin: 4px; } + .learning-prediction button:hover, .lesson-movement button:hover { background: var(--bg-card-hover); } + .lesson-movement { display: flex; flex-wrap: wrap; gap: 16px; align-items: center; margin: 24px 0; } + .lesson-movement a { padding: 8px 0; } + #lessonTitle, #checkpointTitle, #learningCourse :is(a,button,summary,[tabindex]) { scroll-margin-top: 110px; scroll-margin-bottom: 24px; } + @media (max-width: 768px) { .lesson-layout { grid-template-columns: minmax(0,1fr); gap: 20px; } .lesson-outline ol { display: flex; flex-wrap: wrap; gap: 6px 24px; } .lesson-reading .snippet-header { flex-wrap: wrap; gap: 8px; } .learning-diffs { grid-template-columns: minmax(0,1fr); } } + @media (max-width: 900px) { #lessonTitle, #checkpointTitle, #learningCourse :is(a,button,summary,[tabindex]) { scroll-margin-top: 180px; } } + @media (max-width: 600px) { .learning-table-help { display: block; font-size: 0.9rem; } } [data-destination="reference"] .task-navigator { margin-top: 20px; } [data-destination="learn"] #fourZoneModel, [data-destination="learn"] #commitGraphExplorer { display: block !important; } .recovery-recipe { line-height: 1.6; } @@ -2427,8 +2501,11 @@

Learn Git

Follow these existing lessons in order. Each step links to a concept, then its commands.

-
  1. Repositories and saved commits
  2. Choose what to stage
  3. Follow files from disk to the remote
  4. Understand branches and merges
+

Learn Git

Practise with plain-text files, predict what Git will do, then inspect the result.

+
+
Concept illustrations and advanced examples +

Concept illustrations and existing explanations

+
  1. Repositories and saved commits
  2. Choose what to stage
  3. Compare Git content locations
  4. Understand branches and merges
@@ -2436,7 +2513,7 @@

Learn Git

Follow these existing lessons in order. Each step links to Learn Git

Files, staging and commits

How Git actually works: intuitive conceptual models before diving into commands.

-
Quick Concept: Repo = Time Machine • Commit = Save Point • Staging = Cart • 5-Step Safe Routine
+
Quick Concept: Working directory → index → commit → remote
@@ -2481,7 +2558,7 @@

Files, staging and commits

Remote & Pipelines
Cloud Storage & Configured Robot
-

GitHub is a cloud host for your repo. A Pipeline is a robot that runs automated tests and deploys, if your repository has a workflow file configured.

+

A remote is another repository, reached through a configured name such as origin. Fetch updates your local observations of its branches; push publishes commits. A remote can be a local directory or a repository hosted by a service such as GitHub.

@@ -2540,13 +2617,21 @@

Working files, staging and commits

- These four locations describe different Git states; they are not four separate copies of every file. Click any zone card or simulation step to trace how code advances forward, what git status reports at each checkpoint, and which prerequisites each undo operation needs: + Compare the same file’s committed, indexed and working contents. Staging copies content; it does not move files off disk. Checkpoint controls change this illustration only. Zone cards explain operation types and their prerequisites.

- - -
The Shopping Cart (.git/index)
+
Selected content (.git/index)
Changes to be committed
-

The staging index. A curated staging cart where you gather only the files ready to be photographed in your next save point.

+

The index holds the selected content for the next commit. It can differ from both the last commit and the working file.

+

Example indexed notes.txt

Version 1
@@ -2600,9 +2687,10 @@

Zone 3 Local Repository -
The Vault / Save Points (HEAD)
+
Objects and references
Committed snapshots

Committed snapshots in .git/objects. Keep important commits reachable and maintain external backups.

+

Example HEAD:notes.txt

Version 1
@@ -2612,11 +2700,12 @@

@@ -2629,6 +2718,7 @@

Interactive Visual Map

🗺️ Branches, commits and HEAD

Each time you create a commit, Git records the staged snapshot and links it to its parent commits. Saving a file in your editor changes the working file only. Choose an example to see how commits, branches and HEAD relate:

+

Compare branch creation, fast-forward and merge states before and after each action

@@ -2663,12 +2753,12 @@

🗺️ Branches, commits and HEAD

-
-
- Under the Hood: Actual .git/ Files - Live File System State -
-

See exactly what 41-byte text files Git reads and writes inside the hidden .git/ database for this scenario:

+
+ + Example Git metadata + Illustration + +

These invented SHA-1 values illustrate HEAD and loose branch references for the standalone diagram above. The course uses its own labelled checkpoints. This page does not read your repository. References may also be packed or use another storage backend; object ID length depends on the repository’s hash format. Git repository layout

.git/HEAD
@@ -2681,7 +2771,7 @@

🗺️ Branches, commits and HEAD

40-char SHA-1 hash pointing to commit c3
- +
@@ -2691,7 +2781,7 @@

🗺️ Branches, commits and HEAD

- While real-world analogies (save points, breadcrumbs, bookmarks, camera lens) provide an intuitive daily mental model, under the hood Git is a Directed Acyclic Graph (DAG) built atop an immutable content-addressable object store. Here is the formal technical architecture: + Git history is a Directed Acyclic Graph (DAG) built atop an immutable content-addressable object store. Here is the formal technical architecture:

@@ -2718,26 +2808,26 @@

2. Content-Addressable Object Store

3. References (Refs) & Symbolic Refs

Branches and HEAD are lightweight pointers, not folder copies:

    -
  • Branch Ref: A 41-byte text file in .git/refs/heads/<branch-name> containing a single 40-character hexadecimal commit hash. When you commit, Git writes the commit object and updates this file.
    • -
  • HEAD (Symbolic Ref): The file .git/HEAD contains ref: refs/heads/main, delegating where the working tree is anchored. In detached HEAD state, .git/HEAD holds a raw commit hash instead of a branch path.
    • -
  • Remote-Tracking Refs: Read-only pointers in .git/refs/remotes/origin/ reflecting the last known commit on the remote server.
    • +
  • Branch Ref: A name such as refs/heads/main that identifies a commit. A loose reference can be stored in .git/refs/heads/, but references can also be packed or stored using another backend. Committing on a branch updates its reference.
    • +
  • HEAD (Symbolic Ref): In this loose-reference example, .git/HEAD contains ref: refs/heads/main, naming the checked-out branch. In detached HEAD state, HEAD directly identifies a commit instead of naming a branch.
    • +
  • Remote-Tracking Refs: Local references such as refs/remotes/origin/main updated by fetch to record an observed remote branch tip. They can be stale until you communicate with the remote again.

4. Best Common Ancestor (BCA) & 3-Way Merge

How Git calculates merges without manual guesswork:

    -
  • Lowest Common Ancestor (LCA): When merging two branches (B1 and B2), Git traverses the DAG backwards to find their Best Common Ancestor commit A.
    • -
  • 3-Way Diff Matrix: Git computes Δ1 = diff(A, B1) and Δ2 = diff(A, B2). Clean changes to disjoint lines are automatically combined. Changes to identical lines trigger conflict markers.
    • -
  • Merge Commit: The resulting snapshot has two parent pointers: Parent 1 (B1) and Parent 2 (B2).
    • +
  • Common base in this example: The two branches (B1 and B2) share ancestor A, used to compare their changes.
    • +
  • 3-Way Diff Matrix: Git computes Δ1 = diff(A, B1) and Δ2 = diff(A, B2). Non-overlapping changes can combine automatically. Incompatible overlapping changes can conflict; identical edits need not conflict.
    • +
  • Merge Commit: A new merge commit for this diverged two-branch example has two parent pointers: Parent 1 (B1) and Parent 2 (B2). A fast-forward creates no new commit.
- +