docs: add polish and clarity improvements to test suite

Documentation improvements:
- Add environment assumptions to git integration tests
  Tests now clearly document they require git clone with origin remote
- Add "Environment Requirements" section to README_contributors.md
- Document gh-pages internal API dependency and upgrade process
  Explains getRemoteUrl dependency on gh-pages/lib/git (internal API)
  Provides clear upgrade path for v6 with fallback options

Comment improvements:
- Fix "EXCEPTION" comment in engine.spec.ts to match CLAUDE.md policy
  .toContain() is allowed for variable strings, not an exception
- Add provenance comments to error message assertions
  Document exact gh-pages v3.2.3 error messages (lib/git.js lines 213-223)
- Add strict whitelist note to EXPECTED_GIT_COMMANDS
  Explains intentional fail-fast behavior for new git commands in v6

TEST_COVERAGE_PLAN.md updates:
- Clarify test count (351) as historical milestone
- Document manual upgrade strategy for gh-pages v6
  No dual-version harness (intentional) - use manual comparison
- Add detailed 5-step upgrade process with failure categorization

gh-pages.clean() investigation:
- Verified clean() is synchronous in v3.2.3 (uses fs.removeSync)
- Determined setTimeout pattern is appropriate (no callback available)

All 351 tests passing. Test suite documentation now provides clear upgrade path.

Author: JohannesHoppe

TEST_COVERAGE_PLAN.md

@@ -191,6 +191,28 @@ Add `"types": "index.d.ts"` to package.json
 
 All behavioral tests for gh-pages v3.2.3 are now complete and provide comprehensive baseline for v6 upgrade.
 
+### 4.3 Upgrade Strategy for gh-pages v6+
+
+**Manual Upgrade Process:**
+
+We intentionally rely on the existing test suite for upgrade verification rather than maintaining a dual-version test harness:
+
+1. **Establish baseline:** Run `npm test` with gh-pages v3.2.3 - all 351 tests should pass
+2. **Upgrade:** Update gh-pages dependency to v6.x in package.json
+3. **Run tests:** Execute `npm test` with v6 and capture all failures
+4. **Analyze failures systematically:**
+   - Check `engine.prepare-options-helpers.spec.ts` getRemoteUrl tests first (likely internal API changes)
+   - Review `engine.gh-pages-behavior.spec.ts` for behavioral changes
+   - Examine `engine.gh-pages-integration.spec.ts` for API signature changes
+5. **Categorize each failure:**
+   - **Expected breaking changes** in gh-pages v6 → adapt our code
+   - **Bugs in gh-pages v6** → report upstream or work around
+   - **Our incorrect assumptions about v3** → fix our tests
+
+**No Dual-Version Harness:**
+
+We do NOT maintain automated tooling to run tests against both versions simultaneously. This is intentional - the manual comparison process ensures careful evaluation of each change. If automated comparison becomes necessary, it can be added later.
+
 ---
 
 ## Implementation Order
@@ -215,7 +237,7 @@ All behavioral tests for gh-pages v3.2.3 are now complete and provide comprehens
 
 ## Success Criteria
 
-- **Test Count:** 213 → 351 tests (comprehensive suite, see test files for current count)
+- **Test Count:** 213 → 351 tests (historical milestone - use `npm test` output for current count)
 - **Coverage:** ✅ All critical paths tested (error callbacks, monkeypatch, file creation, getRemoteUrl, dotfiles)
 - **Refactoring:** ✅ prepareOptions split into 6 testable functions
 - **Public API:** ✅ Types exported via public_api.ts, TypeScript declarations enabled

docs/README_contributors.md

@@ -155,6 +155,10 @@ cd angular-cli-ghpages/src
 npm test
 ```
 
+**Environment Requirements:**
+
+Some tests (remote URL discovery and `getRemoteUrl` integration tests) expect to run inside a real git clone of this repository with an `origin` remote configured. Running tests from a zip file or bare copy without `.git` is not supported and will cause test failures.
+
 ### 5. Debugging
 
 To debug angular-cli-ghpages you need to:
@@ -247,6 +251,27 @@ const result = await angularDeploy(context, builderConfig, 'your-project-name');
 
 **Note:** The CLI (`ng deploy`) remains the primary and recommended way to use this tool. Programmatic usage is considered advanced/experimental and may change between versions.
 
+## Dependency on gh-pages Internal API
+
+### Remote URL Discovery
+
+The `getRemoteUrl` function in `src/engine/engine.prepare-options-helpers.ts` calls into `gh-pages/lib/git`, which is an **internal API** not documented in gh-pages' public interface. This dependency carries upgrade risk.
+
+**What we depend on:**
+- `new Git(process.cwd(), options.git).getRemoteUrl(options.remote)` from `gh-pages/lib/git`
+- The exact error message format when remote doesn't exist or not in a git repository
+
+**Upgrade process for gh-pages v6+:**
+
+1. Check test failures in `src/engine/engine.prepare-options-helpers.spec.ts` first, specifically the `getRemoteUrl` test block
+2. If those tests fail, it likely indicates a breaking change in gh-pages' internal Git API
+3. Options:
+   - If `gh-pages/lib/git` still exists with same interface: update our error message assertions
+   - If the internal API changed significantly: implement our own git remote discovery using `child_process.execSync('git config --get remote.{remote}.url')`
+   - If gh-pages added a public API for this: switch to the public API
+
+**Current baseline:** Tests are pinned to gh-pages v3.2.3 behavior and error messages.
+
 ## Keeping track of all the forks
 
 [ngx-deploy-starter](https://github.com/angular-schule/ngx-deploy-starter/) and

src/engine/engine.gh-pages-behavior.spec.ts

@@ -43,7 +43,13 @@ function createMockChildProcess(): Partial<ChildProcess> {
   return child;
 }
 
-// Whitelist of expected git commands (fail fast on unexpected commands)
+/**
+ * Whitelist of expected git commands from gh-pages v3.2.3
+ *
+ * Strict whitelist: If gh-pages adds new git subcommands in v6,
+ * this array must be updated first and tests will fail loudly.
+ * This is intentional - we want to know about any new git operations.
+ */
 const EXPECTED_GIT_COMMANDS = [
   'clone', 'clean', 'fetch', 'checkout', 'ls-remote', 'reset',
   'rm', 'add', 'config', 'diff-index', 'commit', 'tag', 'push', 'update-ref'

src/engine/engine.prepare-options-helpers.spec.ts

@@ -590,6 +590,14 @@ describe('prepareOptions helpers - intensive tests', () => {
      * comment in engine.prepare-options-helpers.ts for fallback options.
      */
 
+    /**
+     * Environment assumptions for this test:
+     * - Tests must be run from a git clone of angular-schule/angular-cli-ghpages
+     * - The "origin" remote must exist and point to that repository
+     * - git must be installed and on PATH
+     *
+     * If run from a bare copy of files (no .git), this test will fail by design.
+     */
     it('should return correct URL from git config and be consistent', async () => {
       // This test verifies the internal API returns ACTUAL git config values
       const options = { remote: 'origin' };
@@ -613,7 +621,8 @@ describe('prepareOptions helpers - intensive tests', () => {
         remote: 'nonexistent-remote-12345' // Remote that definitely doesn't exist
       };
 
-      // gh-pages v3.2.3 throws this exact error message for non-existent remotes
+      // Expected message from gh-pages v3.2.3 (lib/git.js lines 213-223)
+      // If this fails after upgrading gh-pages, the internal API changed
       await expect(helpers.getRemoteUrl(options))
         .rejects
         .toThrow('Failed to get remote.nonexistent-remote-12345.url (task must either be run in a git repository with a configured nonexistent-remote-12345 remote or must be configured with the "repo" option).');
@@ -629,7 +638,8 @@ describe('prepareOptions helpers - intensive tests', () => {
         process.chdir(tempDir);
         const options = { remote: 'origin' };
 
-        // gh-pages v3.2.3 throws this exact error message when not in a git repo
+        // Expected message from gh-pages v3.2.3 (lib/git.js lines 213-223)
+        // Note: gh-pages returns same error for both "not in git repo" and "remote doesn't exist"
         await expect(helpers.getRemoteUrl(options))
           .rejects
           .toThrow('Failed to get remote.origin.url (task must either be run in a git repository with a configured origin remote or must be configured with the "repo" option).');

src/engine/engine.spec.ts

@@ -90,15 +90,24 @@ describe('engine', () => {
     });
 
     // NEW in 0.6.2: always discover remote URL (if not set)
+    /**
+     * Environment assumptions for this test:
+     * - Tests must be run from a git clone of angular-schule/angular-cli-ghpages
+     * - The "origin" remote must exist and point to that repository
+     * - git must be installed and on PATH
+     *
+     * If run from a bare copy of files (no .git), this test will fail by design.
+     */
     // this allows us to inject tokens from environment even if --repo is not set manually
     // it uses gh-pages lib directly for this
     it('should discover the remote url, if no --repo is set', async () => {
       const options = {};
       const finalOptions = await engine.prepareOptions(options, logger);
 
-      // EXCEPTION to testing philosophy: Use .toContain() here because the protocol
-      // (SSH: git@github.com: vs HTTPS: https://github.com/) depends on developer's
-      // git config. We only care that the correct repo is discovered.
+      // Justification for .toContain():
+      // The protocol (SSH vs HTTPS) depends on developer's git config.
+      // Our testing philosophy allows .toContain() for substrings in long/variable messages.
+      // We only care that the correct repo path is discovered.
       expect(finalOptions.repo).toContain('angular-schule/angular-cli-ghpages');
     });