agentic-workflow-manager 9.20.1 → 9.20.3

package/dist/tests/commands/change/validate.test.js

@@ -334,7 +334,7 @@ describe('base resolution (R3.1, R3.2, R3.5)', () => {
         expectFailure(r, 'base-unresolved');
         expect(r.stderr).toContain('remedy: pass --base <ref>');
     });
-    test('no main, master or origin/HEAD is base-unresolved', () => {
+    test('no default base resolves: base-unresolved', () => {
         repo.git('branch', '-m', 'main', 'trunk');
         expectFailure((0, change_1.runChangeValidate)(repo.root, undefined, {}), 'base-unresolved');
     });
@@ -794,7 +794,7 @@ describe('R4.5 operational failures under --json', () => {
         ['path-invalid (hostile path)', 'path-invalid', () => (0, change_1.runChangeValidate)(repo.root, `docs/changes/\u001b${'z\n'.repeat(400)}.md`, J)],
         ['git-failed', 'git-failed', () => { jest.spyOn(gitModule, 'headSha').mockReturnValue(null); return (0, change_1.runChangeValidate)(repo.root, undefined, J); }],
         ['flag-invalid', 'flag-invalid', () => (0, change_1.runChangeValidate)(repo.root, undefined, (0, helpers_1.bad)({ ...J, base: 7 }))],
-        ['internal-error', 'internal-error', () => { jest.spyOn(gitModule, 'resolveBaseCommit').mockImplementation(() => { throw new RangeError('x'); }); return (0, change_1.runChangeValidate)(repo.root, undefined, J); }],
+        ['internal-error', 'internal-error', () => { jest.spyOn(gitModule, 'baseCandidates').mockImplementation(() => { throw new RangeError('x'); }); return (0, change_1.runChangeValidate)(repo.root, undefined, J); }],
     ];
     test.each(cases)('%s prints one JSON line of the report shape on stdout and exits 2', (_name, code, call) => {
         const r = call();
@@ -911,7 +911,7 @@ describe('one derivation, one ancestry check and one late-file listing per verif
         let result;
         const calls = gitCalls(() => { result = run(); });
         expect(report(result)).toMatchObject({ state: 'valid', records: [{ state: 'valid' }, { state: 'valid' }] });
-        expect(calls.filter((a) => a.includes('--no-merges'))).toHaveLength(1); // the derivation's git log
+        expect(calls.filter((a) => a.includes('--no-merges'))).toHaveLength(2); // the derivation's full log and its focus log
         expect(calls.filter((a) => a.includes('--is-ancestor'))).toHaveLength(1);
         expect(calls.filter((a) => a.includes('diff') && a.includes(verified))).toHaveLength(1); // the late-file listing
     });

package/dist/tests/commands/changes/list.test.js

@@ -389,6 +389,7 @@ describe('registerChangesCommand', () => {
     test('registers changes list with its documented flags', () => {
         expect(sub()?.options.map((o) => o.long).sort()).toEqual(['--base', '--format', '--since']);
         expect(sub()?.registeredArguments).toEqual([]);
+        expect(sub()?.options.find((o) => o.long === '--base')?.description).toBe('base branch (default: origin/HEAD, origin/main, origin/master, main, master)');
     });
     test('a run prints the result and leaves the exit code alone', async () => {
         history();

package/dist/tests/core/changes/derive.test.js

@@ -129,6 +129,18 @@ describe('deriveFromCommits and deriveModules (no repository)', () => {
         expect(result.diagnostic.message).toContain('abc\\ndef');
         expect(result.diagnostic.message.length).toBeLessThanOrEqual(300);
     });
+    test('R3.3 (amended) type and scope come from the focus commits; semver and breaking from all', () => {
+        const all = [c('docs', 'plans'), c('ci', 'release'), c('docs', 'plans'), c('feat', 'plans', true)];
+        const focus = [c('ci', 'release')];
+        expect((0, derive_1.deriveFromCommits)(all, focus)).toEqual({ type: 'ci', scope: 'release', semver: 'major', breaking: true });
+    });
+    test('R3.3 (amended) an empty, unusable or non-array focus falls back to all commits', () => {
+        const all = [c('docs', 'plans'), c('ci', 'release')];
+        const expected = (0, derive_1.deriveFromCommits)(all);
+        for (const focus of [[], [{ type: 'x y', scope: null, breaking: false, subject: '' }], undefined, null, 'x']) {
+            expect((0, derive_1.deriveFromCommits)(all, focus)).toEqual(expected);
+        }
+    });
 });
 describe('deriveFields in a repository', () => {
     let repo;
@@ -293,11 +305,29 @@ describe('deriveFields in a repository', () => {
         const result = (0, derive_1.deriveFields)(nonRepoDir(), 'a'.repeat(40));
         expect(result).toEqual({ ok: false, diagnostic: expect.objectContaining({ code: 'git-failed' }) });
     });
-    test('deriveFields works from a subdirectory of the repository', () => {
+    test('deriveFields reports git-failed when only the focus log (the one that drops docs/plans) fails', () => {
         const base = branch();
+        repo.commit({ 'cli/src/a.ts': '1' }, 'feat(c): a');
+        const mb = (0, git_1.mergeBase)(repo.root, base);
+        // Only the second `git log` carries the docs/plans exclusion: the full log, HEAD and the diff all succeed.
+        const git = (0, helpers_1.spyOnGit)((args) => { if (args.includes(':(top,exclude,literal)docs/plans'))
+            throw new Error('focus log failed'); });
+        try {
+            expect((0, derive_1.deriveFields)(repo.root, mb)).toEqual({ ok: false, diagnostic: expect.objectContaining({ code: 'git-failed' }) });
+        }
+        finally {
+            git.restore();
+        }
+        expect(git.calls.filter((a) => a[0] === 'log')).toHaveLength(2);
+    });
+    test('deriveFields works from a subdirectory of the repository, and still drops the top-level docs/plans there', () => {
+        const base = branch();
+        // Two plan-only commits: were docs/plans read relative to cli/ (no `top`), they would choose the scope.
+        repo.commit({ 'docs/plans/p.md': '1' }, 'docs(plans): plan it');
+        repo.commit({ 'docs/plans/p.md': '2' }, 'docs(plans): amend it');
         repo.commit({ 'cli/src/a.ts': '1', 'top.ts': '1' }, 'feat(c): top and sub');
         const sub = path_1.default.join(repo.root, 'cli');
-        expect((0, derive_1.deriveFields)(sub, (0, git_1.mergeBase)(repo.root, base))).toEqual({ ok: true, fields: { type: 'feat', scope: 'c', semver: 'minor', breaking: false, modules: ['.', 'cli/src'] } });
+        expect((0, derive_1.deriveFields)(sub, (0, git_1.mergeBase)(repo.root, base))).toEqual({ ok: true, fields: { type: 'feat', scope: 'c', semver: 'minor', breaking: false, modules: ['.', 'cli/src', 'docs/plans'] } });
     });
     test('R3.3 a signed breaking commit is derived even with log.showSignature on', () => {
         const base = branch();
@@ -432,6 +462,49 @@ describe('deriveFields in a repository', () => {
         }
         expect(moved).toBe(true);
     });
+    test('R3.3 (amended) plan-only commits do not choose type or scope (the #228 shape)', () => {
+        const base = branch();
+        repo.commit({ 'docs/plans/p.md': '1' }, 'docs(plans): plan it');
+        repo.commit({ '.github/workflows/ci.yml': '1' }, 'ci(release): shard');
+        repo.commit({ 'docs/plans/p.md': '2' }, 'docs(plans): amend A1');
+        repo.commit({ 'docs/plans/p.md': '3' }, 'docs(plans): amend A2');
+        repo.commit({ '.github/workflows/release.yml': '1' }, 'ci(release): gate it');
+        repo.commit({ 'docs/decisions.md': '1' }, 'docs(decisions): record it');
+        expect((0, derive_1.deriveFields)(repo.root, (0, git_1.mergeBase)(repo.root, base))).toEqual({ ok: true, fields: { type: 'ci', scope: 'release', semver: 'none', breaking: false, modules: ['.github/workflows', 'docs', 'docs/plans'] } });
+    });
+    test('R3.3 (amended) a plan-only commit still counts for semver and breaking', () => {
+        const base = branch();
+        repo.commit({ 'docs/plans/p.md': '1' }, 'feat(plans)!: plan a breaking change');
+        repo.commit({ 'cli/src/a.ts': '1' }, 'fix(process): code');
+        expect((0, derive_1.deriveFields)(repo.root, (0, git_1.mergeBase)(repo.root, base))).toEqual({ ok: true, fields: { type: 'fix', scope: 'process', semver: 'major', breaking: true, modules: ['cli/src', 'docs/plans'] } });
+    });
+    test('R3.3 (amended) a commit touching docs/plans and code counts for type and scope', () => {
+        const base = branch();
+        repo.commit({ 'cli/src/a.ts': '1' }, 'chore(x): first');
+        repo.commit({ 'docs/plans/p.md': '1', 'cli/src/b.ts': '1' }, 'docs(plans): mixed');
+        repo.commit({ 'docs/plans/p.md': '2', 'cli/src/c.ts': '1' }, 'docs(plans): mixed again');
+        expect((0, derive_1.deriveFields)(repo.root, (0, git_1.mergeBase)(repo.root, base))).toMatchObject({ ok: true, fields: { type: 'chore', scope: 'plans' } });
+    });
+    test('R3.3 (amended) a pure planning branch keeps type and scope from its plan commits', () => {
+        const base = branch();
+        repo.commit({ 'docs/plans/p.md': '1' }, 'docs(plans): plan only');
+        expect((0, derive_1.deriveFields)(repo.root, (0, git_1.mergeBase)(repo.root, base))).toEqual({ ok: true, fields: { type: 'docs', scope: 'plans', semver: 'none', breaking: false, modules: ['docs/plans'] } });
+    });
+    test('R3.3 (amended) only the top-level docs/plans is excluded, not similarly named directories', () => {
+        const base = branch();
+        // docs/plans-old decides the type (the only feat) and cli/docs/plans the scope (nested 2 against archive 1): excluding
+        // either directory as well would change the result (chore, or the archive/nested tie broken to archive).
+        repo.commit({ 'docs/plans-old/p.md': '1' }, 'feat(archive): old plans');
+        repo.commit({ 'cli/docs/plans/p.md': '1' }, 'chore(nested): nested plans');
+        repo.commit({ 'cli/src/a.ts': '1' }, 'chore(nested): code');
+        expect((0, derive_1.deriveFields)(repo.root, (0, git_1.mergeBase)(repo.root, base))).toMatchObject({ ok: true, fields: { type: 'feat', scope: 'nested' } });
+    });
+    test('R3.3 (amended) non-conventional code commits leave type and scope to every conventional commit, here the plan', () => {
+        const base = branch();
+        repo.commit({ 'cli/x.ts': '1' }, 'Update the code');
+        repo.commit({ 'docs/plans/p.md': '1' }, 'docs(plans): plan it');
+        expect((0, derive_1.deriveFields)(repo.root, (0, git_1.mergeBase)(repo.root, base))).toEqual({ ok: true, fields: { type: 'docs', scope: 'plans', semver: 'none', breaking: false, modules: ['cli', 'docs/plans'] } });
+    });
 });
 describe('commitsFromRecords: hostile subjects are never handed to the release parser (R3.3), in linear time', () => {
     // The release parser's header regex backtracks quadratically on blanks followed by a line terminator its `.` cannot cross, so a

package/dist/tests/core/changes/git.test.js

@@ -68,7 +68,7 @@ describe('git functions in a repository', () => {
     test('returns null for a directory that does not exist', () => {
         expect((0, git_1.runGit)(path_1.default.join(repo.home, 'missing'), ['status'])).toBeNull();
     });
-    test('R3.1 resolves base: explicit, origin/HEAD, main, master', () => {
+    test('R3.1 resolves base: explicit, origin/HEAD, origin/main, origin/master, main, master', () => {
         branch();
         expect(baseOf(repo.root)).toBe('main');
         expect(baseOf(repo.root, 'main')).toBe('main');
@@ -76,6 +76,39 @@ describe('git functions in a repository', () => {
         repo.git('symbolic-ref', 'refs/remotes/origin/HEAD', 'refs/remotes/origin/main');
         expect(baseOf(repo.root)).toBe('refs/remotes/origin/HEAD');
     });
+    test('R3.1 without origin/HEAD, origin/main wins over a local main', () => {
+        branch();
+        repo.git('update-ref', 'refs/remotes/origin/main', 'main');
+        expect(baseOf(repo.root)).toBe('refs/remotes/origin/main');
+    });
+    test('R3.1 origin/master is used when there is no origin/HEAD nor origin/main, before a local main', () => {
+        branch();
+        repo.git('update-ref', 'refs/remotes/origin/master', 'main');
+        expect(baseOf(repo.root)).toBe('refs/remotes/origin/master');
+    });
+    test('R3.1 with origin/main and origin/master on different commits and no origin/HEAD, origin/main is the base', () => {
+        branch();
+        repo.commit({ 'a.ts': '1' }, 'feat: a');
+        repo.git('update-ref', 'refs/remotes/origin/master', 'main');
+        repo.git('update-ref', 'refs/remotes/origin/main', 'HEAD');
+        expect(repo.git('rev-parse', 'refs/remotes/origin/main')).not.toBe(repo.git('rev-parse', 'refs/remotes/origin/master'));
+        expect((0, git_1.resolveBaseCommit)(repo.root)).toEqual({ base: 'refs/remotes/origin/main', sha: repo.git('rev-parse', 'refs/remotes/origin/main') });
+    });
+    test('R3.1 origin/HEAD still wins over origin/main', () => {
+        branch();
+        repo.git('update-ref', 'refs/remotes/origin/main', 'main');
+        repo.git('update-ref', 'refs/remotes/origin/trunk', 'main');
+        repo.git('symbolic-ref', 'refs/remotes/origin/HEAD', 'refs/remotes/origin/trunk');
+        expect(baseOf(repo.root)).toBe('refs/remotes/origin/HEAD');
+    });
+    test('R3.1 a local branch named origin/main is not taken for the remote candidate', () => {
+        repo.git('branch', 'origin/main');
+        expect(baseOf(repo.root)).toBe('main');
+    });
+    test('R3.1 an explicit base never falls back to origin/main', () => {
+        repo.git('update-ref', 'refs/remotes/origin/main', 'main');
+        expect(baseOf(repo.root, 'nope')).toBeNull();
+    });
     test('R3.1 an explicit base wins over origin/HEAD and main', () => {
         branch();
         repo.git('branch', 'release');
@@ -89,6 +122,55 @@ describe('git functions in a repository', () => {
         repo.git('branch', '-m', 'main', 'trunk');
         expect(baseOf(repo.root)).toBe('master');
     });
+    test.each(['main', 'master'])('R3.1 (Q10) a tag named %s does not redirect the local default, and the base keeps its short name', (name) => {
+        branch();
+        if (name === 'master')
+            repo.git('branch', '-m', 'main', 'master');
+        const tagged = repo.commit({ 'tagged.ts': '1' }, 'feat: tagged');
+        repo.git('tag', name, tagged);
+        expect(repo.git('rev-parse', name)).toBe(tagged); // git alone prefers the tag
+        expect((0, git_1.resolveBaseCommit)(repo.root)).toEqual({ base: name, sha: repo.git('rev-parse', `refs/heads/${name}`) });
+    });
+    test('R3.1 a tag literally named refs/heads/main is not the absent branch main: the base is master', () => {
+        branch();
+        repo.git('branch', '-m', 'main', 'master');
+        const tagged = repo.commit({ 'tagged.ts': '1' }, 'feat: tagged');
+        repo.git('tag', 'refs/heads/main', tagged);
+        expect(repo.git('rev-parse', 'refs/heads/main')).toBe(tagged); // git alone falls through to refs/tags/refs/heads/main
+        expect((0, git_1.resolveBaseCommit)(repo.root)).toEqual({ base: 'master', sha: repo.git('rev-parse', 'refs/heads/master') });
+    });
+    test('R3.1 a tag literally named refs/remotes/origin/main is not the absent remote branch: the base is main', () => {
+        branch();
+        const tagged = repo.commit({ 'tagged.ts': '1' }, 'feat: tagged');
+        repo.git('tag', 'refs/remotes/origin/main', tagged);
+        expect(repo.git('rev-parse', 'refs/remotes/origin/main')).toBe(tagged);
+        expect((0, git_1.resolveBaseCommit)(repo.root)).toEqual({ base: 'main', sha: repo.git('rev-parse', 'refs/heads/main') });
+    });
+    test('R3.1 only an exact refname counts: a branch main/x does not make refs/heads/main exist (a tag of that name is not it)', () => {
+        branch();
+        repo.git('branch', '-m', 'main', 'master');
+        repo.git('branch', 'main/x', 'master'); // `for-each-ref refs/heads/main` lists refs/heads/main/x
+        const tagged = repo.commit({ 'tagged.ts': '1' }, 'feat: tagged');
+        repo.git('tag', 'refs/heads/main', tagged);
+        expect(repo.git('for-each-ref', '--format=%(refname)', 'refs/heads/main')).toBe('refs/heads/main/x');
+        expect((0, git_1.resolveBaseCommit)(repo.root)).toEqual({ base: 'master', sha: repo.git('rev-parse', 'refs/heads/master') });
+    });
+    test('R3.1 when git cannot list the default refs, no default is taken (fail closed)', () => {
+        const git = (0, helpers_1.spyOnGit)((args) => { if (args.includes('for-each-ref'))
+            throw new Error('boom'); });
+        try {
+            expect((0, git_1.resolveBaseCommit)(repo.root)).toBeNull();
+        }
+        finally {
+            git.restore();
+        }
+    });
+    test('R3.1 an explicit base keeps git\'s own resolution (a tag counts)', () => {
+        branch();
+        const tagged = repo.commit({ 'tagged.ts': '1' }, 'feat: tagged');
+        repo.git('tag', 'v1', tagged);
+        expect((0, git_1.resolveBaseCommit)(repo.root, 'v1')).toEqual({ base: 'v1', sha: tagged });
+    });
     test('R3.1 origin/HEAD that points nowhere is skipped', () => {
         repo.git('symbolic-ref', 'refs/remotes/origin/HEAD', 'refs/remotes/origin/gone');
         expect(baseOf(repo.root)).toBe('main');

package/dist/tests/core/changes/list.test.js

@@ -28,14 +28,15 @@ describe('listChanges: input and base (R5.1, R3.1, R3.2, R3.5)', () => {
         adopt();
         expect(listed().base).toBe('main');
     });
-    test('the default base costs one rev-parse per candidate tried, not a second one to pin it', () => {
+    test('the default base costs one for-each-ref for all candidates and one rev-parse per existing candidate, not a second one to pin it', () => {
         adopt();
         const spy = (0, helpers_1.spyOnGit)();
         listed();
         spy.restore();
         const asked = (ref) => spy.calls.filter((a) => a.includes(`${ref}^{commit}`)).length;
-        expect(asked('refs/remotes/origin/HEAD')).toBe(1);
-        expect(asked('main')).toBe(1);
+        expect(spy.calls.filter((a) => a.includes('for-each-ref') && a.includes('refs/heads/main'))).toHaveLength(1);
+        expect(asked('refs/remotes/origin/HEAD')).toBe(0); // absent: never handed to rev-parse
+        expect(asked('refs/heads/main')).toBe(1); // the local default resolves as the full ref (Q10)
     });
     test('an explicit base is used and reported', () => {
         adopt();
@@ -568,7 +569,7 @@ describe('listChanges: derived fields (R5.5)', () => {
             const spy = (0, helpers_1.spyOnGit)();
             listed();
             spy.restore();
-            const lookups = spy.calls.filter((a) => a.includes('for-each-ref'));
+            const lookups = spy.calls.filter((a) => a.includes('for-each-ref') && a.includes('refs/tags/')); // the tag lookup, not the base's
             expect(lookups).toHaveLength(1);
             expect(lookups[0]).toContain('--count=500');
         });
@@ -610,7 +611,7 @@ describe('listChanges: derived fields (R5.5)', () => {
     test('a git failure while looking for the tags is git-failed, never a release of null', () => {
         adopt();
         repo.commit({ 'a.ts': '1' }, 'fix: a', '2026-10-16T10:00:00Z');
-        const spy = (0, helpers_1.spyOnGit)((args) => { if (args.includes('for-each-ref'))
+        const spy = (0, helpers_1.spyOnGit)((args) => { if (args.includes('for-each-ref') && args.includes('refs/tags/'))
             throw new Error('boom'); });
         const outcome = list();
         spy.restore();

package/dist/tests/core/changes/range.test.js

@@ -1,7 +1,13 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 const helpers_1 = require("./helpers");
 const command_1 = require("../../../src/core/changes/command");
+const git_1 = require("../../../src/core/changes/git");
 const range_1 = require("../../../src/core/changes/range");
 let repo;
 /** A repository for the groups that need one (the pure recordDirProblem tests need none). */
@@ -40,11 +46,94 @@ describe('resolveRange', () => {
         expect((0, range_1.resolveRange)(repo.root, 'main')).toMatchObject({ ok: false, failure: { code: 'base-unresolved', remedy: 'pass --base <ref>' } });
         expect((0, range_1.resolveRange)(repo.root, 'main').failure.message).toContain('no merge base');
     });
+    /** A commit on its own branch from main, made shallow (no parents as far as git can tell): it shares no merge base with feat/x. */
+    function shallowCommit() {
+        repo.git('checkout', '-q', '-b', 'up', 'main');
+        const up = repo.commit({ 'up.ts': '1' }, 'feat: upstream');
+        repo.git('checkout', '-q', 'feat/x');
+        repo.git('branch', '-D', 'up');
+        fs_1.default.writeFileSync(path_1.default.join(repo.root, '.git', 'shallow'), `${up}\n`);
+        return up;
+    }
+    test('R3.1 (Q7) without --base, a shallow origin/main with no merge base gives way to a connected local main', () => {
+        const main = (0, helpers_1.branchOff)(repo);
+        const head = repo.commit({ 'a.ts': '1' }, 'feat: a');
+        const up = shallowCommit();
+        repo.git('update-ref', 'refs/remotes/origin/main', up);
+        expect((0, range_1.resolveRange)(repo.root, undefined)).toEqual({ ok: true, head, mergeBase: main });
+        // `changes list` needs no merge base: it keeps the first candidate that names a commit.
+        expect((0, range_1.resolveBaseRef)(repo.root, undefined)).toEqual({ ok: true, base: 'refs/remotes/origin/main', sha: up });
+    });
+    test('R3.1 (Q7) an explicit --base without a merge base is base-unresolved: no fallback to the defaults', () => {
+        (0, helpers_1.branchOff)(repo);
+        repo.commit({ 'a.ts': '1' }, 'feat: a');
+        repo.git('branch', 'shallow', shallowCommit());
+        expect((0, range_1.resolveRange)(repo.root, 'shallow')).toEqual({ ok: false, failure: { code: 'base-unresolved', message: 'no merge base between "shallow" and HEAD', remedy: 'pass --base <ref>' } });
+    });
+    test('R3.1 (Q7) without --base, when no default that names a commit has a merge base, the failure names the first of them', () => {
+        (0, helpers_1.branchOff)(repo);
+        repo.commit({ 'a.ts': '1' }, 'feat: a');
+        const up = shallowCommit();
+        repo.git('update-ref', 'refs/remotes/origin/main', up);
+        repo.git('update-ref', 'refs/heads/main', up);
+        expect((0, range_1.resolveRange)(repo.root, undefined)).toEqual({ ok: false, failure: { code: 'base-unresolved', message: 'no merge base between "refs/remotes/origin/main" and HEAD', remedy: 'pass --base <ref>' } });
+    });
+    test('R3.1 without --base, a tag literally named refs/heads/main is not taken for the absent branch main', () => {
+        (0, helpers_1.branchOff)(repo);
+        const head = repo.commit({ 'a.ts': '1' }, 'feat: a');
+        const master = repo.git('rev-parse', 'main');
+        repo.git('branch', '-m', 'main', 'master');
+        repo.git('tag', 'refs/heads/main', head);
+        expect((0, range_1.resolveRange)(repo.root, undefined)).toEqual({ ok: true, head, mergeBase: master });
+    });
+    test('R3.1 (Q9) the merge base comes from the commit id the base resolved to, not from the base name read again', () => {
+        const main = (0, helpers_1.branchOff)(repo);
+        const head = repo.commit({ 'a.ts': '1' }, 'feat: a');
+        const elsewhere = shallowCommit();
+        let moved = false;
+        const git = (0, helpers_1.spyOnGit)((args) => {
+            if (!moved && args[0] === 'merge-base') {
+                moved = true;
+                repo.git('update-ref', 'refs/heads/main', elsewhere);
+            }
+        });
+        try {
+            expect((0, range_1.resolveRange)(repo.root, undefined)).toEqual({ ok: true, head, mergeBase: main });
+        }
+        finally {
+            git.restore();
+        }
+        expect(moved).toBe(true);
+    });
     test('an unreadable HEAD is git-failed', () => {
         expect((0, range_1.resolveRange)((0, helpers_1.nonRepoDir)(repo), undefined)).toMatchObject({ ok: false, failure: { code: 'git-failed' } });
         expect((0, range_1.resolveRange)((0, helpers_1.bad)(undefined), undefined)).toMatchObject({ ok: false, failure: { code: 'git-failed' } });
     });
 });
+describe('BASE_OPTION_HELP (R3.1, Q6)', () => {
+    test('names the default candidates in order', () => {
+        expect(range_1.BASE_OPTION_HELP).toBe('base branch (default: origin/HEAD, origin/main, origin/master, main, master)');
+    });
+    test('is built from the candidate list, not written by hand', () => {
+        jest.isolateModules(() => {
+            jest.doMock('../../../src/core/changes/git', () => ({
+                ...jest.requireActual('../../../src/core/changes/git'),
+                DEFAULT_BASES: [{ ref: 'refs/remotes/origin/trunk', name: 'refs/remotes/origin/trunk' }, { ref: 'refs/heads/dev', name: 'dev' }],
+            }));
+            expect(require('../../../src/core/changes/range').BASE_OPTION_HELP).toBe('base branch (default: origin/trunk, dev)');
+        });
+        jest.dontMock('../../../src/core/changes/git');
+    });
+    test('the default candidates are the remote ones, then the local branches as full refs that report their short name', () => {
+        expect(git_1.DEFAULT_BASES).toEqual([
+            { ref: 'refs/remotes/origin/HEAD', name: 'refs/remotes/origin/HEAD' },
+            { ref: 'refs/remotes/origin/main', name: 'refs/remotes/origin/main' },
+            { ref: 'refs/remotes/origin/master', name: 'refs/remotes/origin/master' },
+            { ref: 'refs/heads/main', name: 'main' },
+            { ref: 'refs/heads/master', name: 'master' },
+        ]);
+    });
+});
 describe('headMovedFailure', () => {
     withRepo();
     test('HEAD moving has its own code, and it is an operational failure (exit 2) like the others', () => {

package/dist/tests/core/frontmatter-hardening.test.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// FH-1 / FH-2 / FH-3: linear plain-scalar comment strip, YAML-aligned
+// space/tab-before-# vs NBSP, and exact `---` closer for matchFrontmatterBlock.
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const frontmatter_1 = require("../../src/core/frontmatter");
+const helpers_1 = require("./changes/helpers");
+describe('frontmatter hardening (FH-1, FH-2, FH-3)', () => {
+    describe('FH-3: matchFrontmatterBlock closes only on exact ---', () => {
+        it('keeps keys after a ---x line inside the block', () => {
+            const raw = '---\nname: a\n---x: 1\nstatus: b\n---\n\nbody\n';
+            const block = (0, frontmatter_1.matchFrontmatterBlock)(raw);
+            expect(block).not.toBeNull();
+            expect(block).toContain('---x: 1');
+            expect(block).toContain('status: b');
+        });
+        it('closes on --- with trailing spaces', () => {
+            const block = (0, frontmatter_1.matchFrontmatterBlock)('---\nname: a\n--- \n\nbody\n');
+            expect(block).toBe('name: a');
+        });
+        it('closes on --- with trailing tabs and CRLF', () => {
+            const block = (0, frontmatter_1.matchFrontmatterBlock)('---\r\nname: a\r\n---\t\t\r\n\r\nbody\r\n');
+            expect(block).toBe('name: a');
+        });
+        it('does not close on ---#comment', () => {
+            const raw = '---\nname: a\n---#comment\nstatus: b\n---\n\nbody\n';
+            const block = (0, frontmatter_1.matchFrontmatterBlock)(raw);
+            expect(block).not.toBeNull();
+            expect(block).toContain('---#comment');
+            expect(block).toContain('status: b');
+        });
+        it('yields empty string for empty frontmatter', () => {
+            expect((0, frontmatter_1.matchFrontmatterBlock)('---\n---\n')).toBe('');
+        });
+        it('does not close on --- followed by NBSP', () => {
+            const raw = '---\nname: a\n---\u00A0\nstatus: b\n---\n\nbody\n';
+            const block = (0, frontmatter_1.matchFrontmatterBlock)(raw);
+            expect(block).not.toBeNull();
+            expect(block).toContain('---\u00A0');
+            expect(block).toContain('status: b');
+        });
+        it('returns null quickly when open frontmatter would exceed 65536 without a closer', () => {
+            const huge = `---\n${'x'.repeat(70_000)}`;
+            const started = Date.now();
+            expect((0, frontmatter_1.matchFrontmatterBlock)(huge)).toBeNull();
+            expect(Date.now() - started).toBeLessThan(500);
+        });
+        it('returns null when a closer exists only after inner content would exceed 65536', () => {
+            // Without the allocation bound, this would return a 65537-char block.
+            const raw = `---\n${'x'.repeat(65_537)}\n---\n`;
+            const started = Date.now();
+            expect((0, frontmatter_1.matchFrontmatterBlock)(raw)).toBeNull();
+            expect(Date.now() - started).toBeLessThan(500);
+        });
+    });
+    describe('FH-2: comment strip is space/tab only (not NBSP)', () => {
+        it('drops trailing comment after space before #', () => {
+            expect((0, frontmatter_1.findFrontmatterDescription)('description: hello # drop').value).toBe('hello');
+        });
+        it('drops trailing comment after tab before #', () => {
+            expect((0, frontmatter_1.findFrontmatterDescription)('description: hello\t# drop').value).toBe('hello');
+        });
+        it('keeps NBSP before # (matches js-yaml)', () => {
+            const fm = 'description: hello\u00A0# keep';
+            const ours = (0, frontmatter_1.findFrontmatterDescription)(fm).value;
+            const doc = js_yaml_1.default.load(fm);
+            expect(ours).toBe(doc.description);
+            expect(ours).toContain('\u00A0');
+            expect(ours).toContain('# keep');
+        });
+        it('keeps # with no whitespace before it (C#)', () => {
+            expect((0, frontmatter_1.findFrontmatterDescription)('description: usar C# y F#').value).toBe('usar C# y F#');
+        });
+    });
+    describe('FH-1: plain description comment strip is linear-time', () => {
+        it('scales linearly with long runs of spaces and no #', () => {
+            (0, helpers_1.expectLinearScaling)((n) => {
+                (0, frontmatter_1.findFrontmatterDescription)('description: a' + ' '.repeat(n) + 'x');
+            }, 20_000);
+        });
+        it('scales linearly with long runs of tabs and no #', () => {
+            (0, helpers_1.expectLinearScaling)((n) => {
+                (0, frontmatter_1.findFrontmatterDescription)('description: a' + '\t'.repeat(n) + 'x');
+            }, 20_000);
+        });
+    });
+});