agentic-workflow-manager 9.20.1 → 9.20.2

package/dist/src/commands/change/index.js

@@ -475,7 +475,7 @@ function registerChangeCommand(program, deps = {}) {
     change
         .command('new <slug>')
         .description('create docs/changes/YYYY-MM-DD-<slug>.md with derived fields and pending narrative')
-        .option('--base <ref>', 'base branch (default: origin/HEAD, main, master)')
+        .option('--base <ref>', range_1.BASE_OPTION_HELP)
         .option('--plan <path>', 'repo-relative plan file to link')
         .option('--issue <url>', 'https issue URL to link')
         .option('--model <model>', 'provenance: model identifier')
@@ -485,7 +485,7 @@ function registerChangeCommand(program, deps = {}) {
     change
         .command('validate [path]')
         .description('validate the Change Record(s) added by this branch, or one record (--strict also checks the sensor receipt)')
-        .option('--base <ref>', 'base branch (default: origin/HEAD, main, master)')
+        .option('--base <ref>', range_1.BASE_OPTION_HELP)
         .option('--strict', 'require a matching, passing sensor receipt for verification.commit')
         .option('--json', 'print a single JSON line')
         .action((target, opts) => inCwd((cwd) => runChangeValidate(cwd, target, opts), wantsJson(opts)));

package/dist/src/commands/changes/index.js

@@ -10,6 +10,7 @@ const command_1 = require("../../core/changes/command");
 const git_1 = require("../../core/changes/git");
 const list_1 = require("../../core/changes/list");
 const list_parse_1 = require("../../core/changes/list-parse");
+const range_1 = require("../../core/changes/range");
 const render_list_1 = require("../../core/changes/render-list");
 const text_safety_1 = require("../../core/changes/text-safety");
 const FORMATS = ['text', 'json', 'voice'];
@@ -78,7 +79,7 @@ function registerChangesCommand(program, deps = {}) {
         .command('list')
         .description('list the changes of the base branch with their Change Record and derived merge/release state')
         .option('--since <window>', '<n>h, <n>d or YYYY-MM-DD (default 24h)')
-        .option('--base <ref>', 'base branch (default: origin/HEAD, main, master)')
+        .option('--base <ref>', range_1.BASE_OPTION_HELP)
         .option('--format <format>', 'text | json | voice (default text)')
         .action((opts) => (0, command_1.inCwd)((cwd) => runChangesList(cwd, opts, deps), () => (0, command_1.fail)('not-a-git-repo', 'the working directory is not accessible')));
 }

package/dist/src/core/changes/derive.js

@@ -15,6 +15,7 @@ const types_1 = require("./types");
 // Pathspecs relative to the repository top, so the result does not depend on the directory git runs in.
 const ALL_FILES = ':/';
 const EXCLUDE_RECORDS = `:(top,exclude,literal)${types_1.RECORD_DIR}`;
+const EXCLUDE_PLANS = ':(top,exclude,literal)docs/plans';
 const PARSER_TYPE = /^\w+$/;
 const RECORD_TYPE = /^[a-z]+$/;
 const MODULE_DEPTH = 3;
@@ -39,18 +40,22 @@ function usable(commits) {
 }
 const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
 /**
- * R3.3. `breaking` and `semver` cover every usable commit, with the release parser's exact-type semantics; the recorded type is
- * the highest-impact commit's type lowercased, or `other` when that is still not purely letters. Null when no commit is usable.
+ * R3.3 as amended 2026-10-19. `breaking` and `semver` cover every usable commit, with the release parser's exact-type semantics.
+ * `type` and `scope` come from the usable `focus` commits (those touching a path outside docs/changes/ and docs/plans/), or from
+ * every usable commit when `focus` is omitted or has none. The recorded type is the highest-impact chosen commit's type
+ * lowercased, or `other` when that is still not purely letters. Null when no commit is usable.
  */
-function deriveFromCommits(input) {
+function deriveFromCommits(input, focusInput) {
     const commits = usable(input);
     if (commits.length === 0)
         return null;
+    const focused = usable(focusInput);
+    const chooser = focused.length > 0 ? focused : commits;
     const breaking = commits.some((c) => c.breaking);
-    const pick = commits.find((c) => c.breaking) ?? commits.find((c) => c.type === 'feat') ?? commits.find((c) => c.type === 'fix')
-        ?? commits.find((c) => c.type === 'perf') ?? commits[0];
+    const pick = chooser.find((c) => c.breaking) ?? chooser.find((c) => c.type === 'feat') ?? chooser.find((c) => c.type === 'fix')
+        ?? chooser.find((c) => c.type === 'perf') ?? chooser[0];
     const counts = new Map();
-    for (const c of commits)
+    for (const c of chooser)
         if (c.scope)
             counts.set(c.scope, (counts.get(c.scope) ?? 0) + 1);
     const scope = [...counts.entries()].sort((a, b) => b[1] - a[1] || byCodeUnit(a[0], b[0]))[0]?.[0] ?? null;
@@ -87,6 +92,8 @@ function commitsFromRecords(records) {
 const fail = (code, message) => ({ ok: false, diagnostic: { code, message: (0, text_safety_1.clipMessage)(message) } });
 /**
  * Derives from the non-merge commits in mergeBaseSha..HEAD, ignoring commits and files that only touch docs/changes/.
+ * R3.3 amended: `type` and `scope` come from the commits that also touch a path outside docs/plans/ (all of them when no
+ * conventional commit does), while `semver` and `breaking` cover every commit.
  * `mergeBaseSha` must be a full commit id (the output of `mergeBase`); anything else is `invalid-input`.
  */
 function deriveFields(root, mergeBaseSha) {
@@ -103,14 +110,20 @@ function deriveFields(root, mergeBaseSha) {
     // (`merge -s ours`), silently dropping real commits from the range.
     // -z ends every commit with NUL, which a message cannot contain: each record is exactly one commit, so a message that
     // embeds the parser's own separator cannot be read as a second commit.
-    const raw = (0, git_1.runGit)(root, ['log', ...git_1.LOG_SAFETY_ARGS, '--no-merges', '--full-history', '--reverse', '-z', `--format=${core_1.GIT_LOG_FORMAT}`, '--end-of-options', range, '--', ALL_FILES, EXCLUDE_RECORDS]);
+    const logArgs = ['log', ...git_1.LOG_SAFETY_ARGS, '--no-merges', '--full-history', '--reverse', '-z', `--format=${core_1.GIT_LOG_FORMAT}`, '--end-of-options', range, '--', ALL_FILES, EXCLUDE_RECORDS];
+    const raw = (0, git_1.runGit)(root, logArgs);
     if (raw === null)
         return fail('git-failed', `git could not read the commits in ${range}`);
     const records = raw.split('\0').filter((record) => record !== '');
     if (records.length === 0)
         return fail('no-commits', `no non-merge commits outside ${types_1.RECORD_DIR}/ in ${range}`);
     const commits = commitsFromRecords(records);
-    const derived = deriveFromCommits(commits);
+    // R3.3 amended: plan-only commits do not choose type or scope, so a second log over the same range drops docs/plans/.
+    const focusRaw = (0, git_1.runGit)(root, [...logArgs, EXCLUDE_PLANS]);
+    if (focusRaw === null)
+        return fail('git-failed', `git could not read the commits in ${range}`);
+    const focus = commitsFromRecords(focusRaw.split('\0').filter((record) => record !== ''));
+    const derived = deriveFromCommits(commits, focus);
     if (derived === null)
         return fail('no-conventional-commits', 'no commit in the range uses a conventional-commit subject (type(scope): subject)');
     const files = (0, git_1.changedFiles)(root, mergeBaseSha, head);

package/dist/src/core/changes/git.js

@@ -3,11 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LOG_SAFETY_ARGS = void 0;
+exports.DEFAULT_BASES = exports.LOG_SAFETY_ARGS = void 0;
 exports.runGit = runGit;
 exports.runGitBytes = runGitBytes;
 exports.isSafeRef = isSafeRef;
 exports.isSafeRevision = isSafeRevision;
+exports.baseCandidates = baseCandidates;
 exports.resolveBaseCommit = resolveBaseCommit;
 exports.mergeBase = mergeBase;
 exports.isAncestor = isAncestor;
@@ -81,14 +82,44 @@ function isSafeRevision(rev) {
     return parts.length <= 2 && parts.every(isSafeRef);
 }
 /**
- * R3.1: --base, then origin/HEAD, then main, then master: the first that names a commit, with that commit's id. Null when none
- * does (or the explicit base is unsafe). One `rev-parse` per candidate.
+ * R3.1 (amended 2026-10-19): the default base candidates, remote first so a stale local branch is the last resort. The local
+ * branches resolve as full refs (git would otherwise prefer a tag `main` over the branch) but are reported by their short name.
+ */
+exports.DEFAULT_BASES = [
+    { 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' },
+];
+/**
+ * The DEFAULT_BASES whose exact ref exists, in order (one `for-each-ref` for all of them; a broken symref is not listed). Without
+ * this check git's rev-parse would fall through to `refs/tags/<ref>`, so a tag literally named `refs/heads/main` could stand in for
+ * an absent branch. The patterns are constants; only an exact refname match counts (a pattern also lists the refs below it).
+ * Empty when git fails: the defaults then fail closed as unresolved.
+ */
+function existingDefaultBases(root) {
+    const out = runGit(root, ['for-each-ref', '--format=%(refname)', '--end-of-options', ...exports.DEFAULT_BASES.map((c) => c.ref)]);
+    const present = new Set((out ?? '').split('\n'));
+    return exports.DEFAULT_BASES.filter((c) => present.has(c.ref));
+}
+/**
+ * R3.1: the candidates for a base, in order. An explicit base is the only one (no fallback) and keeps git's own resolution;
+ * otherwise the DEFAULT_BASES whose exact ref exists. Every caller (`resolveBaseCommit`, `resolveRange`) takes its order from here.
+ */
+function baseCandidates(root, explicit) {
+    return explicit !== undefined ? [{ ref: explicit, name: explicit }] : existingDefaultBases(root);
+}
+/**
+ * R3.1: --base, then origin/HEAD, origin/main, origin/master, main, master: the first that names a commit, with that commit's id.
+ * An explicit base is the only candidate (no fallback). Null when none does (or the explicit base is unsafe). One `rev-parse` per
+ * candidate tried (and, for the defaults, one `for-each-ref`).
  */
 function resolveBaseCommit(root, explicit) {
-    for (const candidate of explicit !== undefined ? [explicit] : ['refs/remotes/origin/HEAD', 'main', 'master']) {
-        const sha = commitSha(root, candidate);
+    for (const { ref, name } of baseCandidates(root, explicit)) {
+        const sha = commitSha(root, ref);
         if (sha !== null)
-            return { base: candidate, sha };
+            return { base: name, sha };
     }
     return null;
 }

package/dist/src/core/changes/range.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HEAD_MOVED = void 0;
+exports.HEAD_MOVED = exports.BASE_OPTION_HELP = void 0;
 exports.resolveBaseRef = resolveBaseRef;
 exports.resolveRange = resolveRange;
 exports.headMovedFailure = headMovedFailure;
@@ -9,34 +9,49 @@ const git_1 = require("./git");
 const text_safety_1 = require("./text-safety");
 const types_1 = require("./types");
 const REMEDY_BASE = 'pass --base <ref>';
+/** R3.1: the `--base` help text of `change new`, `change validate` and `changes list`: `DEFAULT_BASES` (git.ts) in order, remotes without `refs/remotes/`. */
+exports.BASE_OPTION_HELP = `base branch (default: ${git_1.DEFAULT_BASES.map((c) => c.name.replace(/^refs\/remotes\//, '')).join(', ')})`;
 exports.HEAD_MOVED = { code: 'head-moved', message: 'HEAD moved during derivation' };
 const KINDS = ['ok', 'absent', 'unsafe', 'error'];
 const failure = (code, message, remedy) => ({ ok: false, failure: remedy === undefined ? { code, message } : { code, message, remedy } });
+const unsafeBase = (explicitBase) => failure('invalid-input', `--base "${(0, text_safety_1.esc)(explicitBase)}" is not a safe git ref`);
 /**
- * R3.1/R3.2/R3.5: the base ref: `explicitBase` (checked with `isSafeRef` before git sees it: `invalid-input`), else origin/HEAD,
- * main, master; `base-unresolved` when none resolves. The one place that decides it, for `change new`, `change validate` and `changes list`.
+ * R3.1/R3.2/R3.5, for `changes list`: the base ref: `explicitBase` (checked with `isSafeRef` before git sees it: `invalid-input`),
+ * else the first default candidate that names a commit (no merge base is needed); `base-unresolved` when none does. The order of the
+ * candidates has one source, `baseCandidates` (git.ts), shared with `resolveRange`.
  */
 function resolveBaseRef(root, explicitBase) {
     if (explicitBase !== undefined && !(0, git_1.isSafeRef)(explicitBase))
-        return failure('invalid-input', `--base "${(0, text_safety_1.esc)(explicitBase)}" is not a safe git ref`);
+        return unsafeBase(explicitBase);
     const resolved = (0, git_1.resolveBaseCommit)(root, explicitBase);
     return resolved === null ? failure('base-unresolved', 'could not resolve a base branch', REMEDY_BASE) : { ok: true, ...resolved };
 }
 /**
- * R3.1/R3.2/R3.5: pins HEAD, then resolves the base (explicit `--base`, else origin/HEAD, main, master) and its merge base with HEAD.
- * An explicit base is checked with `isSafeRef` before git sees it.
+ * R3.1/R3.2/R3.5, for `change new` and `change validate`: pins HEAD, then resolves the base and its merge base with HEAD, over the
+ * same `baseCandidates` (git.ts) as `resolveBaseRef` but also requiring a merge base. An explicit `--base` (checked with `isSafeRef`
+ * before git sees it) is the only candidate. Without it (R3.1 amended, Q7), the first default candidate that names a commit AND has
+ * a merge base with HEAD: a shallow remote ref that does not reach HEAD gives way to the next.
+ * The merge base is computed from the commit id the candidate resolved to, never from its name read a second time (Q9).
  */
 function resolveRange(root, explicitBase) {
     const head = (0, git_1.headSha)(root);
     if (head === null)
         return failure('git-failed', 'git could not read HEAD');
-    const resolved = resolveBaseRef(root, explicitBase);
-    if (!resolved.ok)
-        return resolved;
-    const mergeBaseSha = (0, git_1.mergeBase)(root, resolved.base);
-    if (mergeBaseSha === null)
-        return failure('base-unresolved', `no merge base between "${(0, text_safety_1.esc)(resolved.base)}" and HEAD`, REMEDY_BASE);
-    return { ok: true, head, mergeBase: mergeBaseSha };
+    if (explicitBase !== undefined && !(0, git_1.isSafeRef)(explicitBase))
+        return unsafeBase(explicitBase);
+    let named = null;
+    for (const { ref, name } of (0, git_1.baseCandidates)(root, explicitBase)) {
+        const sha = (0, git_1.commitSha)(root, ref);
+        if (sha === null)
+            continue;
+        named ??= name;
+        const mergeBaseSha = (0, git_1.mergeBase)(root, sha);
+        if (mergeBaseSha !== null)
+            return { ok: true, head, mergeBase: mergeBaseSha };
+    }
+    if (named === null)
+        return failure('base-unresolved', 'could not resolve a base branch', REMEDY_BASE);
+    return failure('base-unresolved', `no merge base between "${(0, text_safety_1.esc)(named)}" and HEAD`, REMEDY_BASE);
 }
 /** `HEAD_MOVED` when HEAD is no longer `head` (or cannot be read), else null: a verdict about a moving target is never given. */
 function headMovedFailure(root, head) {

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

@@ -781,7 +781,7 @@ describe('awm change new: base and derivation diagnostics (R3.1, R3.2, R3.5)', (
         receiptForHead();
         expectFailure(run('ok', { base: 'nope' }), 'base-unresolved', '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');
         receiptForHead();
         expectFailure(run('ok'), 'base-unresolved', 'pass --base <ref>');
@@ -794,6 +794,29 @@ describe('awm change new: base and derivation diagnostics (R3.1, R3.2, R3.5)', (
         run('change-record', { base: 'mid' });
         expect(frontmatter(read())).toMatchObject({ type: 'fix', scope: 'core', semver: 'patch', modules: ['cli/src'] });
     });
+    test('a #228-shaped branch (plan commits first, then ci(release) commits) records type ci and scope release', () => {
+        repo.git('checkout', '-q', '-b', 'ci/shard', 'main');
+        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');
+        receiptForHead();
+        expect(run('change-record').code).toBe(0);
+        expect(frontmatter(read())).toMatchObject({ type: 'ci', scope: 'release', semver: 'none', breaking: false, modules: ['.github/workflows', 'docs/plans'] });
+    });
+    test('without origin/HEAD, a current origin/main is the base, not a stale local main', () => {
+        repo.git('checkout', '-q', '-b', 'upstream', 'main');
+        repo.commit({ 'other/u.ts': '1' }, 'feat(other)!: merged upstream');
+        repo.git('update-ref', 'refs/remotes/origin/main', 'upstream');
+        repo.git('checkout', '-q', '-b', 'feat/y', 'upstream');
+        repo.git('branch', '-D', 'upstream');
+        repo.commit({ 'cli/src/m.ts': '1' }, 'fix(core): mine');
+        receiptForHead();
+        expect(run('change-record').code).toBe(0);
+        // Against the stale local main, the upstream breaking feat would be in the range.
+        expect(frontmatter(read())).toMatchObject({ type: 'fix', scope: 'core', semver: 'patch', breaking: false, modules: ['cli/src'] });
+    });
     test('a branch with no commits beyond the base is no-commits', () => {
         repo.git('checkout', '-q', 'main');
         expectFailure(run('ok'), 'no-commits');
@@ -1096,6 +1119,10 @@ describe('registerChangeCommand', () => {
         const change = program().commands.find((c) => c.name() === 'change');
         const sub = change?.commands.find((c) => c.name() === 'new');
         expect(sub?.options.map((o) => o.long).sort()).toEqual(['--base', '--issue', '--model', '--plan', '--refresh', '--session']);
+        for (const name of ['new', 'validate']) {
+            const base = change?.commands.find((c) => c.name() === name)?.options.find((o) => o.long === '--base');
+            expect(base?.description).toBe('base branch (default: origin/HEAD, origin/main, origin/master, main, master)');
+        }
     });
     test('the change command describes both of its subcommands', () => {
         expect(program().commands.find((c) => c.name() === 'change')?.description()).toBe('create and validate the Change Record of the current branch');

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/structural/native-release-artifacts.test.js

@@ -5,25 +5,161 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
 const CLI_ROOT = path_1.default.resolve(__dirname, '..', '..');
 const REPO_ROOT = path_1.default.resolve(CLI_ROOT, '..');
 function readWorkflow(name) {
     return fs_1.default.readFileSync(path_1.default.join(REPO_ROOT, '.github', 'workflows', name), 'utf8').replace(/\r\n/g, '\n');
 }
-function assertArmPartition(source) {
+const HOT_IGNORE = String.raw `node_modules|[/\\]cli[/\\]tests[/\\]commands[/\\]watch[/\\]track-(finalize|freeze)\.test\.ts$`;
+const CHANGES_PATTERN = String.raw `[/\\]cli[/\\]tests[/\\](core[/\\]changes|commands[/\\]changes?)[/\\]`;
+const HOT_STEP = 'Test hot Windows ARM suites';
+const CHANGES_STEP = 'Test Change Record Windows ARM suites';
+const CHANGES_RUN = `npx jest --runInBand --bail --testPathPatterns='${CHANGES_PATTERN}'`;
+const REMAINDER_COMMENT = "      # The ARM runner's slow suites run in two separate jobs (watch track-finalize/freeze, and the Change Record suites). Keep runInBand within each job; no test file may run twice or be dropped.\n";
+const HOT_RUN = 'npx jest --runTestsByPath tests/commands/watch/track-finalize.test.ts tests/commands/watch/track-freeze.test.ts --runInBand --bail';
+const RELEASE_GATE = ['test', 'windows-arm-changes', 'windows-arm-hot'];
+const SHARD_SETUP = [
+    { uses: 'actions/checkout@v4' },
+    { uses: 'actions/setup-node@v4', with: { 'node-version': '22' } },
+    { name: 'Install', 'working-directory': 'cli', run: 'npm ci' },
+    { name: 'Build', 'working-directory': 'cli', run: 'npm run native:build && npm run build' },
+    { name: 'Build test-only native addon', 'working-directory': 'cli', run: 'npm run native:test-build' },
+];
+// Jest compiles --testPathPatterns with the `i` flag but --testPathIgnorePatterns
+// without it, so a directory differing only in case would run in both the shard
+// and the remainder. Returns every directory that falls in that gap.
+function caseOnlyShardPaths(directories, pattern) {
+    const insensitive = new RegExp(pattern, 'i');
+    const sensitive = new RegExp(pattern);
+    return directories.filter((directory) => {
+        const candidate = `${directory}/`;
+        return insensitive.test(candidate) && !sensitive.test(candidate);
+    });
+}
+const SHARD_DIRECTORIES = [['core', 'changes'], ['commands', 'change'], ['commands', 'changes']];
+// Each real shard directory must exist with its exact case, hold at least one
+// suite and match CHANGES_PATTERN, so the case-only walk cannot pass vacuously.
+function shardDirectoryProblems(testsRoot) {
+    const shard = new RegExp(CHANGES_PATTERN);
+    const problems = [];
+    for (const segments of SHARD_DIRECTORIES) {
+        const label = segments.join('/');
+        let current = testsRoot;
+        let found = true;
+        for (const segment of segments) {
+            // readdirSync keeps the on-disk case even on case-insensitive file systems.
+            if (!fs_1.default.existsSync(current) || !fs_1.default.readdirSync(current).includes(segment)) {
+                found = false;
+                break;
+            }
+            current = path_1.default.join(current, segment);
+        }
+        if (!found) {
+            problems.push(`${label}: missing with this exact case`);
+            continue;
+        }
+        if (!fs_1.default.readdirSync(current).some((entry) => entry.endsWith('.test.ts'))) {
+            problems.push(`${label}: holds no *.test.ts`);
+        }
+        if (!shard.test(`${current}${path_1.default.sep}`)) {
+            problems.push(`${label}: does not match CHANGES_PATTERN`);
+        }
+    }
+    return problems;
+}
+function parseJobs(source) {
+    const parsed = js_yaml_1.default.load(source);
+    expect(parsed?.jobs).toBeDefined();
+    return parsed.jobs;
+}
+function getJob(jobs, name) {
+    const job = jobs[name];
+    expect(job).toBeDefined();
+    expect(Array.isArray(job.steps)).toBe(true);
+    return job;
+}
+function keysOf(value) {
+    return Object.keys(value);
+}
+// The release job publishes only when every test job passed: no if, no
+// continue-on-error, and needs is exactly the three gating jobs in any order.
+function assertReleaseGate(jobs) {
+    const release = getJob(jobs, 'release');
+    expect(keysOf(release)).not.toContain('if');
+    expect(keysOf(release)).not.toContain('continue-on-error');
+    for (const step of release.steps) {
+        expect(keysOf(step)).not.toContain('continue-on-error');
+    }
+    expect(Array.isArray(release.needs)).toBe(true);
+    const needs = release.needs;
+    expect(needs).toHaveLength(RELEASE_GATE.length);
+    expect([...needs].sort()).toEqual(RELEASE_GATE);
+}
+// Gate semantics are asserted on the parsed workflow, so key quoting or escaping
+// cannot hide an if or a continue-on-error. Text is checked only where the exact
+// text is the contract: the run lines and the A1 comment.
+function assertArmPartition(source, gatesRelease) {
     const workflow = source.replace(/\r\n/g, '\n');
-    expect(workflow.match(/^  windows-arm-hot:\s*$/gm)).toHaveLength(1);
-    const [matrixJob, rest] = workflow.split(/^  windows-arm-hot:\s*$/m);
-    expect(rest).toBeDefined();
-    const hotJob = rest.split(/^  [a-z][\w-]*:\s*$/m)[0];
-    // Optional env: (e.g. AWM_BASELINE_REGISTRY_ROOT for RF-5.1 docs contract) may
-    // sit between working-directory and run; release.yml still omits it.
-    expect(matrixJob).toMatch(/- name: Tests?\n        if: matrix\.target != 'win32-arm64'\n        working-directory: cli\n(?:        env:\n(?:          [^\n]+\n)+)?        run: npx jest --runInBand --bail\n/);
-    const remainder = matrixJob.match(/- name: Tests? \(Windows ARM remainder\)\n        if: matrix\.target == 'win32-arm64'\n        working-directory: cli\n(?:        env:\n(?:          [^\n]+\n)+)?        run: ([^\n]+)/)?.[1];
-    expect(remainder).toMatch(/^npx jest --runInBand --bail --testPathIgnorePatterns='[^']+'$/);
-    const ignorePattern = remainder?.match(/--testPathIgnorePatterns='([^']+)'/)?.[1];
-    expect(ignorePattern).toBe(String.raw `node_modules|[/\\]cli[/\\]tests[/\\]commands[/\\]watch[/\\]track-(finalize|freeze)\.test\.ts$`);
+    const jobs = parseJobs(source);
+    const names = keysOf(jobs);
+    const test = getJob(jobs, 'test');
+    const hot = getJob(jobs, 'windows-arm-hot');
+    const changes = getJob(jobs, 'windows-arm-changes');
+    expect(names.indexOf('windows-arm-hot')).toBeGreaterThan(names.indexOf('test'));
+    expect(names.indexOf('windows-arm-changes')).toBe(names.indexOf('windows-arm-hot') + 1);
+    // No gating job tolerates failure, at job or step level.
+    for (const job of [test, hot, changes]) {
+        expect(keysOf(job)).not.toContain('continue-on-error');
+        for (const step of job.steps) {
+            expect(keysOf(step)).not.toContain('continue-on-error');
+        }
+    }
+    // The ARM shards never skip, at job or step level.
+    for (const job of [hot, changes]) {
+        expect(keysOf(job)).not.toContain('if');
+        for (const step of job.steps) {
+            expect(keysOf(step)).not.toContain('if');
+        }
+    }
+    // In the matrix, only the two test steps are guarded, with complementary targets.
+    const guarded = test.steps.filter((step) => keysOf(step).includes('if'));
+    expect(guarded).toHaveLength(2);
+    const [regular, remainder] = guarded;
+    expect(regular.name).toMatch(/^Tests?$/);
+    expect(regular.if).toBe("matrix.target != 'win32-arm64'");
+    expect(regular['working-directory']).toBe('cli');
+    expect(regular.run).toBe('npx jest --runInBand --bail');
+    expect(remainder.name).toMatch(/^Tests? \(Windows ARM remainder\)$/);
+    expect(remainder.if).toBe("matrix.target == 'win32-arm64'");
+    expect(remainder['working-directory']).toBe('cli');
+    const ignorePattern = String(remainder.run).match(/^npx jest --runInBand --bail --testPathIgnorePatterns='([^']+)'$/)?.[1];
+    expect(ignorePattern).toBe(`${HOT_IGNORE}|${CHANGES_PATTERN}`);
+    expect(test.steps.filter((step) => step.uses === 'actions/upload-artifact@v4')).toHaveLength(1);
+    // A1 comment, directly above the remainder step.
+    expect(workflow.split(REMAINDER_COMMENT)).toHaveLength(2);
+    const aroundRemainder = workflow.split(/      - name: Tests? \(Windows ARM remainder\)\n/);
+    expect(aroundRemainder).toHaveLength(2);
+    expect(aroundRemainder[0].endsWith(REMAINDER_COMMENT)).toBe(true);
+    // Both shards share the same setup; only their test step differs.
+    expect(hot['runs-on']).toBe('windows-11-arm');
+    expect(hot.steps.slice(0, -1)).toEqual(SHARD_SETUP);
+    expect(hot.steps.at(-1)).toEqual({ name: HOT_STEP, 'working-directory': 'cli', run: HOT_RUN });
+    expect(changes.steps.at(-1)).toEqual({ name: CHANGES_STEP, 'working-directory': 'cli', run: CHANGES_RUN });
+    expect({ ...changes, steps: changes.steps.slice(0, -1) }).toEqual({ ...hot, steps: hot.steps.slice(0, -1) });
+    if (gatesRelease) {
+        expect(changes.permissions).toEqual({ contents: 'read' });
+    }
+    for (const job of [hot, changes]) {
+        expect(job.steps.some((step) => String(step.uses ?? '').includes('upload-artifact'))).toBe(false);
+        expect(JSON.stringify(job)).not.toContain('secure-fs-win32-arm64');
+    }
+    const lines = workflow.split('\n');
+    expect(lines).toContain(`        run: ${HOT_RUN}`);
+    expect(lines).toContain(`        run: ${CHANGES_RUN}`);
+    // The remainder ignores exactly the hot suites plus what the Change Record shard runs.
     const ignored = new RegExp(ignorePattern);
     for (const separator of ['/', '\\']) {
         const root = ['repo', 'cli', 'tests'].join(separator);
@@ -32,18 +168,100 @@ function assertArmPartition(source) {
             expect(ignored.test([root, 'other', `${suite}.test.ts`].join(separator))).toBe(false);
         }
     }
-    const remainderStep = matrixJob.split(/- name: Tests? \(Windows ARM remainder\)\n/)[1]?.split(/^      - name:/m)[0];
-    expect(remainderStep).toBeDefined();
-    expect(remainderStep).not.toContain('continue-on-error: true');
-    expect(matrixJob.match(/uses: actions\/upload-artifact@v4/g)).toHaveLength(1);
-    expect(hotJob).toContain('runs-on: windows-11-arm');
-    expect(hotJob).toContain('run: npm run native:build');
-    expect(hotJob).toContain('run: npm run native:test-build');
-    expect(hotJob.split('\n')).toContain('        run: npx jest --runTestsByPath tests/commands/watch/track-finalize.test.ts tests/commands/watch/track-freeze.test.ts --runInBand --bail');
-    expect(hotJob).not.toContain('upload-artifact@v4');
-    expect(hotJob).not.toContain('secure-fs-win32-arm64');
-    expect(hotJob).not.toMatch(/^\s*if:/m);
-    expect(hotJob).not.toContain('continue-on-error: true');
+    const shardPattern = String(changes.steps.at(-1)?.run).match(/--testPathPatterns='([^']+)'$/)?.[1];
+    expect(shardPattern).toBe(CHANGES_PATTERN);
+    expect(ignorePattern).toBe(`${HOT_IGNORE}|${shardPattern}`);
+    const shard = new RegExp(shardPattern, 'i');
+    for (const separator of ['/', '\\']) {
+        const root = ['repo', 'cli', 'tests'].join(separator);
+        for (const file of [['core', 'changes', 'x.test.ts'], ['commands', 'change', 'new.test.ts'], ['commands', 'changes', 'list.test.ts']]) {
+            const candidate = [root, ...file].join(separator);
+            expect(shard.test(candidate)).toBe(true);
+            expect(ignored.test(candidate)).toBe(true);
+        }
+        for (const file of [['core', 'changesets', 'x.test.ts'], ['commands', 'changesets', 'x.test.ts'], ['commands', 'watch', 'track-finalize.test.ts']]) {
+            expect(shard.test([root, ...file].join(separator))).toBe(false);
+        }
+        expect(ignored.test([root, 'core', 'changesets', 'x.test.ts'].join(separator))).toBe(false);
+    }
+    if (gatesRelease) {
+        assertReleaseGate(jobs);
+        // CI-2 keeps the comment on the release job's needs line.
+        const releaseText = workflow.slice(workflow.search(/^  release:\n/m));
+        expect(releaseText.match(/^    needs: [^\n]*$/m)?.[0]).toMatch(/ # rojo en cualquier plataforma o shard ARM no publica$/);
+    }
+    else {
+        expect(names).not.toContain('release');
+    }
+}
+// Rewrites the release job's inline `needs` list in the workflow text.
+function rewriteReleaseNeeds(workflow, rewrite) {
+    const header = workflow.search(/^  release:\n/m);
+    expect(header).toBeGreaterThanOrEqual(0);
+    const head = workflow.slice(0, header);
+    const tail = workflow.slice(header).replace(/^(    needs: )\[([^\]\n]*)\]/m, (_line, prefix, list) => `${prefix}[${rewrite(list.split(',').map((job) => job.trim())).join(', ')}]`);
+    return head + tail;
+}
+function permutations(items) {
+    if (items.length <= 1)
+        return [items];
+    return items.flatMap((item, index) => permutations([...items.slice(0, index), ...items.slice(index + 1)]).map((rest) => [item, ...rest]));
+}
+// Every bypass of the partition or the release gate must make assertArmPartition
+// throw: a failed assertion or a mutated text that no longer parses as YAML.
+function assertMutationsRejected(workflow, gates) {
+    const jobLevel = (job, line) => workflow.replace(new RegExp(`^  ${job}:\\n`, 'm'), `  ${job}:\n    ${line}\n`);
+    const inStep = (step, line) => workflow.replace(`      - name: ${step}\n`, `      - name: ${step}\n        ${line}\n`);
+    const mutations = [
+        // Swapped matrix guards.
+        workflow.replace(/if: matrix\.target (?:!=|==) 'win32-arm64'/g, (guard) => guard.includes('!=') ? "if: matrix.target == 'win32-arm64'" : "if: matrix.target != 'win32-arm64'"),
+        // A second producer of the native artifact.
+        workflow.replace('uses: actions/upload-artifact@v4', 'uses: actions/upload-artifact@v4\n      - uses: actions/upload-artifact@v4'),
+        // A remainder that drops more than the shards run.
+        workflow.replace(/(--testPathIgnorePatterns='[^']+)(?=')/, '$1|runner\\.test\\.ts$'),
+        // A shard pattern that differs from the remainder's exclusion.
+        workflow.replace(/(--testPathPatterns='[^']+)changes\?/, '$1changes'),
+        // Masked shard runs.
+        workflow.replace(/(run: npx jest --runTestsByPath [^\n]+ --runInBand --bail)(?=\n)/, '$1; exit 0'),
+        workflow.replace(/(run: npx jest --runInBand --bail --testPathPatterns='[^']+')(?=\n)/, '$1; exit 0'),
+        // Skipped steps or jobs, in any key quoting.
+        inStep(HOT_STEP, 'if: false'),
+        inStep(HOT_STEP, '"if": always()'),
+        inStep(HOT_STEP, "'if': false"),
+        inStep(CHANGES_STEP, 'if: false'),
+        inStep(CHANGES_STEP, '"if": always()'),
+        inStep(CHANGES_STEP, "'if': false"),
+        inStep('Upload native secure-fs artifact', "'if': false"),
+        jobLevel('windows-arm-hot', '"if": always()'),
+        jobLevel('windows-arm-hot', "'if': false"),
+        jobLevel('windows-arm-changes', '"if": always()'),
+        jobLevel('windows-arm-changes', "'if': false"),
+        // Tolerated failures, in any key quoting, escaping or expression form.
+        jobLevel('test', "continue-on-error: ${{ matrix.target == 'win32-arm64' }}"),
+        jobLevel('test', '"continue-on-error": true'),
+        jobLevel('test', '"continue\\x2Don-error": true'),
+        jobLevel('windows-arm-hot', 'continue-on-error: true'),
+        jobLevel('windows-arm-hot', 'continue-on-error: ${{ true }}'),
+        jobLevel('windows-arm-hot', '"continue-on-error": true'),
+        jobLevel('windows-arm-changes', 'continue-on-error: true'),
+        jobLevel('windows-arm-changes', 'continue-on-error: ${{ true }}'),
+        jobLevel('windows-arm-changes', '"continue-on-error": true'),
+        inStep(HOT_STEP, '"continue-on-error": true'),
+        inStep(CHANGES_STEP, "'continue-on-error': true"),
+        workflow.replace(/^(        run: npx jest --runInBand --bail\n)/m, '$1        continue-on-error: true\n'),
+        workflow.replace(/(run: npx jest --runInBand --bail --testPathIgnorePatterns='[^']+'\n)/, '$1        continue-on-error: true\n'),
+        workflow.replace(/(run: npx jest --runInBand --bail --testPathIgnorePatterns='[^']+'\n)/, '$1        continue-on-error: ${{ true }}\n'),
+    ];
+    if (gates) {
+        mutations.push(rewriteReleaseNeeds(workflow, (jobs) => jobs.filter((job) => job !== 'windows-arm-changes')), rewriteReleaseNeeds(workflow, (jobs) => [...jobs, 'windows-arm-changes']), jobLevel('release', 'if: always()'), jobLevel('release', 'if: ${{ !cancelled() }}'), jobLevel('release', '"if": always()'), jobLevel('release', "'if': false"), jobLevel('release', 'continue-on-error: true'), jobLevel('release', '"continue-on-error": true'), 
+        // The needs comment is part of CI-2.
+        workflow.slice(0, workflow.search(/^  release:\n/m))
+            + workflow.slice(workflow.search(/^  release:\n/m)).replace(/^(    needs: [^\n]*?) # rojo en cualquier plataforma o shard ARM no publica$/m, '$1'));
+    }
+    for (const mutated of mutations) {
+        expect(mutated).not.toBe(workflow);
+        expect(() => assertArmPartition(mutated, gates)).toThrow();
+    }
 }
 describe('native release artifacts', () => {
     it('runs each platform suite once without weakening publication', () => {
@@ -54,44 +272,75 @@ describe('native release artifacts', () => {
             expect(workflow).toContain('run: npx jest --runInBand --bail');
         }
         const release = readWorkflow('release.yml');
-        expect(release).toMatch(/release:\s*\n\s*needs: \[test, windows-arm-hot\]/);
+        assertReleaseGate(parseJobs(release));
         for (const target of ['linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64', 'win32-x64', 'win32-arm64']) {
             expect(release).toContain(`target: ${target}`);
         }
         expect(release).toContain('cancel-in-progress: false');
     });
-    it('partitions the two hot ARM suites without duplicating the native artifact', () => {
+    it('partitions the hot and Change Record ARM shards without duplicating the native artifact', () => {
         for (const name of ['ci.yml', 'release.yml']) {
             const workflow = readWorkflow(name);
-            assertArmPartition(workflow);
+            assertArmPartition(workflow, name === 'release.yml');
         }
     });
     it('checks the same partition after a Windows CRLF checkout', () => {
         for (const name of ['ci.yml', 'release.yml']) {
             const workflow = readWorkflow(name);
-            assertArmPartition(workflow.replace(/\n/g, '\r\n'));
+            assertArmPartition(workflow.replace(/\n/g, '\r\n'), name === 'release.yml');
         }
     });
-    it('rejects swapped matrix guards, non-gating hot tests and duplicate artifacts', () => {
+    it('rejects swapped matrix guards, non-gating ARM shards, drifted partitions and duplicate artifacts', () => {
         for (const name of ['ci.yml', 'release.yml']) {
-            const workflow = readWorkflow(name);
-            const swapped = workflow.replace(/if: matrix\.target (?:!=|==) 'win32-arm64'/g, (guard) => guard.includes('!=') ? "if: matrix.target == 'win32-arm64'" : "if: matrix.target != 'win32-arm64'");
-            const nonGating = workflow.replace('  windows-arm-hot:\n', '  windows-arm-hot:\n    continue-on-error: true\n');
-            const duplicateArtifact = workflow.replace('uses: actions/upload-artifact@v4', 'uses: actions/upload-artifact@v4\n      - uses: actions/upload-artifact@v4');
-            const broadIgnore = workflow.replace(/(--testPathIgnorePatterns='[^']+)(?=')/, '$1|runner\\.test\\.ts$');
-            const skippedHot = workflow.replace('      - name: Test hot Windows ARM suites\n', '      - name: Test hot Windows ARM suites\n        if: false\n');
-            const nonGatingRemainder = workflow.replace(/(run: npx jest --runInBand --bail --testPathIgnorePatterns='[^']+'\n)/, '$1        continue-on-error: true\n');
-            const maskedHot = workflow.replace(/(run: npx jest --runTestsByPath [^\n]+ --runInBand --bail)(?=\n)/, '$1; exit 0');
-            for (const mutated of [swapped, nonGating, duplicateArtifact, broadIgnore, skippedHot, nonGatingRemainder, maskedHot]) {
-                expect(mutated).not.toBe(workflow);
+            assertMutationsRejected(readWorkflow(name), name === 'release.yml');
+        }
+    });
+    it('keeps the whole self-test green when release needs is reordered', () => {
+        const workflow = readWorkflow('release.yml');
+        let current = [];
+        rewriteReleaseNeeds(workflow, (jobs) => (current = jobs));
+        const reorderedJobs = permutations(current).find((jobs) => jobs.join() !== current.join());
+        expect(reorderedJobs).toBeDefined();
+        const reordered = rewriteReleaseNeeds(workflow, () => reorderedJobs);
+        expect(reordered).not.toBe(workflow);
+        expect(() => assertArmPartition(reordered, true)).not.toThrow();
+        expect(() => assertMutationsRejected(reordered, true)).not.toThrow();
+    });
+    it('reports a shard directory that is missing, renamed by case or holds no suite', () => {
+        const tmp = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-arm-shard-'));
+        try {
+            const testsRoot = path_1.default.join(tmp, 'cli', 'tests');
+            for (const segments of SHARD_DIRECTORIES) {
+                fs_1.default.mkdirSync(path_1.default.join(testsRoot, ...segments), { recursive: true });
+                fs_1.default.writeFileSync(path_1.default.join(testsRoot, ...segments, 'x.test.ts'), '');
             }
-            expect(() => assertArmPartition(swapped)).toThrow();
-            expect(() => assertArmPartition(nonGating)).toThrow();
-            expect(() => assertArmPartition(duplicateArtifact)).toThrow();
-            expect(() => assertArmPartition(broadIgnore)).toThrow();
-            expect(() => assertArmPartition(skippedHot)).toThrow();
-            expect(() => assertArmPartition(nonGatingRemainder)).toThrow();
-            expect(() => assertArmPartition(maskedHot)).toThrow();
+            expect(shardDirectoryProblems(testsRoot)).toEqual([]);
+            fs_1.default.renameSync(path_1.default.join(testsRoot, 'core', 'changes'), path_1.default.join(testsRoot, 'core', 'Changes'));
+            expect(shardDirectoryProblems(testsRoot)).toEqual([expect.stringContaining('core/changes')]);
+            fs_1.default.renameSync(path_1.default.join(testsRoot, 'core', 'Changes'), path_1.default.join(testsRoot, 'core', 'changes'));
+            fs_1.default.renameSync(path_1.default.join(testsRoot, 'commands', 'change', 'x.test.ts'), path_1.default.join(testsRoot, 'commands', 'change', 'helpers.ts'));
+            expect(shardDirectoryProblems(testsRoot)).toEqual([expect.stringContaining('commands/change')]);
+            fs_1.default.rmSync(path_1.default.join(testsRoot, 'commands', 'changes'), { recursive: true });
+            expect(shardDirectoryProblems(testsRoot)).toHaveLength(2);
+        }
+        finally {
+            fs_1.default.rmSync(tmp, { recursive: true, force: true });
+        }
+    });
+    it('flags test directories that only the case-insensitive shard pattern selects', () => {
+        expect(caseOnlyShardPaths(['repo/cli/tests/core/Changes'], CHANGES_PATTERN)).toEqual(['repo/cli/tests/core/Changes']);
+        expect(caseOnlyShardPaths(['repo\\cli\\tests\\commands\\CHANGE'], CHANGES_PATTERN)).toEqual(['repo\\cli\\tests\\commands\\CHANGE']);
+        expect(caseOnlyShardPaths(['repo/cli/tests/core/changes', 'repo/cli/tests/commands/change', 'repo/cli/tests/core/Changesets'], CHANGES_PATTERN)).toEqual([]);
+    });
+    it('has no test directory selected by the shard but kept by the remainder through case alone', () => {
+        const testsRoot = path_1.default.join(CLI_ROOT, 'tests');
+        const directories = fs_1.default.readdirSync(testsRoot, { recursive: true })
+            .map((relative) => path_1.default.join(testsRoot, relative))
+            .filter((candidate) => fs_1.default.statSync(candidate).isDirectory());
+        expect(shardDirectoryProblems(testsRoot)).toEqual([]);
+        const flagged = caseOnlyShardPaths(directories, CHANGES_PATTERN);
+        if (flagged.length > 0) {
+            throw new Error(`Case-only Change Record directories would run in both ARM shards: ${flagged.join(', ')}`);
         }
     });
     it('keeps native prebuilds generated instead of versioned source', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-workflow-manager",
-  "version": "9.20.1",
+  "version": "9.20.2",
   "main": "dist/src/index.js",
   "bin": {
     "awm": "./dist/src/index.js"