agentic-workflow-manager 9.20.0 → 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/src/core/process/model.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROCESS_NAME = void 0;
 exports.parseProcessFrontmatter = parseProcessFrontmatter;
@@ -7,40 +10,155 @@ exports.parseProcessFrontmatter = parseProcessFrontmatter;
 // Disciplina heredada literal de core/orchestrators.ts: NUNCA lanza. Un modelo
 // malformado se rechaza con diagnóstico y no invalida al registry que lo
 // contiene ni a los demás (R7.1).
+const js_yaml_1 = __importDefault(require("js-yaml"));
 const frontmatter_1 = require("../frontmatter");
 const types_1 = require("./types");
 /** El discriminador es literal: ningún documento se reconoce como modelo por su
  *  cuerpo, sus headings ni su nombre de archivo (R1.2). */
 const DISCRIMINATOR = 'process-model';
-const ALLOWED_FIELDS = ['awm', 'schema', 'name', 'status', 'entry_point', 'terminates_to', 'created', 'updated'];
+/** `description` es el único campo opcional: runtimes como Codex se niegan a
+ *  cargar un `SKILL.md` sin él, y el modelo *es* el `SKILL.md` del skill. */
+const ALLOWED_FIELDS = ['awm', 'schema', 'name', 'status', 'entry_point', 'terminates_to', 'created', 'updated', 'description'];
+/** Límite de Agent Skills que imponen los runtimes que consumen el skill.
+ *  Se cuenta en code points, no en unidades UTF-16. */
+const DESCRIPTION_MAX = 1024;
+/** Tope del bloque de frontmatter antes de entregarlo al parser YAML: acota el
+ *  costo de parsear contenido no confiable de un registry. Por encima no se
+ *  parsea (para `description`, se rechaza con el mensaje del límite de 1024). */
+const FRONTMATTER_MAX = 65536;
+/** Lo que un runtime mostraría mal o usaría para engañar: controles C0 (salvo
+ *  tab), DEL, C1, separadores U+2028/U+2029, marcas LRM/RLM/ALM, overrides e
+ *  isolates bidi, y surrogates sueltos (regex en vez de `isWellFormed`: el lib
+ *  de TS es ES2022). */
+const FORBIDDEN_CHAR = /[\u0000-\u0008\u000A-\u001F\u007F-\u009F\u061C\u200E\u200F\u2028\u2029\u202A-\u202E\u2066-\u2069]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/** Discriminador indentado: un modelo cuyas claves quedaron con sangría se
+ *  perdería en silencio como "no es un modelo". */
+const INDENTED_DISCRIMINATOR = /^awm[ \t]*:[ \t]*process-model$/;
 const STATUSES = ['draft', 'active'];
 /** El slug es lo único del modelo que puede viajar dentro de un id del Dashboard
  *  (ver sanitize.ts). Por eso se valida acá y no en la frontera de render: si
  *  admitiera rutas, markup o `=`, el id dejaría de ser seguro por construcción. */
 exports.PROCESS_NAME = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
 const DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** Caracteres de ancho cero: un valor hecho solo de ellos se ve vacío. */
+const ZERO_WIDTH = /[\u200B-\u200D\u2060\uFEFF]/g;
 /** Lector de pares `clave: valor` de un frontmatter plano. El contrato no admite
- *  anidamiento ni block scalars, así que no se arrastra un parser YAML: cualquier
- *  línea que no sea `clave: valor` es un rechazo, no una interpretación. */
+ *  anidamiento ni block scalars: cualquier línea que no sea `clave: valor` es un
+ *  rechazo, no una interpretación. (El VALOR de `description` sí pasa por el
+ *  parser YAML, más abajo.) */
 function readPairs(block) {
     const pairs = new Map();
     const problems = [];
-    for (const raw of block.split(/\r?\n/)) {
-        const line = raw.trim();
+    const continuations = [];
+    // Mismo criterio que YAML, no que JS: se parte en TODO salto de línea YAML
+    // (un CR suelto también; si no, `a\rclave: x` sería un par para acá y dos
+    // claves para un runtime) y solo se recorta espacio y tab (`\s`/`trim()`
+    // comerían NBSP o U+3000, que para YAML son contenido).
+    const lines = block.split(/\r\n|\r|\n/);
+    for (const [index, raw] of lines.entries()) {
+        const line = raw.replace(/^[ \t]+|[ \t]+$/g, '');
+        // NEL/LS/PS son saltos de línea para YAML 1.1 (PyYAML) y no para js-yaml:
+        // un comentario podría esconder una clave que solo un runtime ve. Se
+        // reporta en CUALQUIER línea, comentarios incluidos, y solo por posición.
+        if (/[\u0085\u2028\u2029]/.test(raw))
+            problems.push(`frontmatter line ${index + 1} contains a YAML 1.1 line break (NEL, LS or PS)`);
         if (line === '' || line.startsWith('#'))
             continue;
-        const m = /^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$/.exec(line);
+        // El contrato es un mapa PLANO: una línea que empieza con espacio o tab
+        // es continuación de un valor multilínea, diga lo que diga. Si se
+        // recortara antes de mirar, `  KEY: x` pasaría por campo (y su nombre
+        // terminaría en un diagnóstico).
+        const indented = /^[ \t]/.test(raw);
+        if (indented)
+            continuations.push({ line: index + 1, text: line });
+        // `[\s\S]` y no `.`: un U+2028/U+2029 dentro del valor no lo vuelve
+        // "no-par" (la línea ya viene partida); lo rechaza el chequeo de controles.
+        const m = indented ? null : /^([A-Za-z_][A-Za-z0-9_]*)[ \t]*:[ \t]*([\s\S]*)$/.exec(line);
+        // Se reporta la POSICIÓN (1-based dentro del bloque), nunca el
+        // contenido: una línea suelta suele ser la continuación de un valor
+        // multilínea, y los diagnósticos no transportan valores de campos.
         if (!m) {
-            problems.push(`line is not a "key: value" pair: ${JSON.stringify(line.slice(0, 80))}`);
+            problems.push(`frontmatter line ${index + 1} is not a "key: value" pair (multi-line values are not supported)`);
             continue;
         }
         if (pairs.has(m[1])) {
             problems.push(`duplicate field ${JSON.stringify(m[1])}`);
             continue;
         }
-        pairs.set(m[1], m[2].trim());
+        pairs.set(m[1], m[2]);
     }
-    return { pairs, problems };
+    return { pairs, problems, continuations };
+}
+/** Carga el bloque de frontmatter COMPLETO con js-yaml (schema por defecto),
+ *  exactamente como lo lee un runtime. Por encima del tope no se parsea. NUNCA
+ *  lanza: un error de js-yaml es `invalid`. */
+function loadBlock(block) {
+    if (block.length > FRONTMATTER_MAX)
+        return { kind: 'too-long' };
+    try {
+        return { kind: 'loaded', doc: js_yaml_1.default.load(block) };
+    }
+    catch {
+        return { kind: 'invalid' };
+    }
+}
+function isPlainObject(doc) {
+    return doc !== null && typeof doc === 'object' && Object.getPrototypeOf(doc) === Object.prototype;
+}
+/** Valida `description` leyéndola del bloque entero con el parser YAML real, no
+ *  de la salida de readPairs (ya recortada y partida en `:`, que difiere de lo
+ *  que lee un runtime). Ni el valor ni el texto del error de js-yaml (que puede
+ *  citar contenido) llegan al problema. */
+/** ¿El valor crudo de la línea, cargado SOLO, da el mismo string que el bloque
+ *  entero? Si no, YAML lo plegó con líneas siguientes (p. ej. una comilla que
+ *  sigue abierta a través de una línea `# …`). NUNCA lanza. */
+function readsSameAlone(raw, value) {
+    let alone;
+    try {
+        alone = js_yaml_1.default.load(`description: ${raw}`);
+    }
+    catch {
+        return false;
+    }
+    return isPlainObject(alone) && alone.description === value;
+}
+function checkDescription(raw, block, keys) {
+    const singleLine = { problem: '"description" must be a single-line string (block scalars are not supported in a process model)' };
+    // El prefijo alcanza: todo header de block scalar (bien o mal formado)
+    // empieza con `>` o `|`.
+    if (/^[>|]/.test(raw))
+        return singleLine;
+    const tooLong = { problem: `"description" must be at most ${DESCRIPTION_MAX} characters` };
+    const loaded = loadBlock(block);
+    if (loaded.kind === 'too-long')
+        return tooLong;
+    if (loaded.kind === 'invalid' || !isPlainObject(loaded.doc))
+        return { problem: '"description" cannot be read: the frontmatter is not valid YAML' };
+    const doc = loaded.doc;
+    // Si YAML lee otras claves de nivel superior que readPairs (un CR suelto,
+    // una comilla que se traga la línea siguiente), lo validado acá no es lo
+    // que verá un runtime. Ni claves ni valores van al problema.
+    const yamlKeys = Object.keys(doc);
+    if (yamlKeys.length !== keys.size || yamlKeys.some((k) => !keys.has(k))) {
+        return { problem: '"description" cannot be read: the frontmatter does not read the same as YAML (check quotes and line breaks)' };
+    }
+    const value = doc.description;
+    const empty = { problem: '"description" must not be empty' };
+    if (value === null || value === undefined)
+        return empty;
+    if (typeof value !== 'string') {
+        return { problem: '"description" must be a string (quote values YAML reads as a boolean, a number, a date or a collection)' };
+    }
+    if (value.replace(ZERO_WIDTH, '').trim() === '')
+        return empty;
+    if ([...value].length > DESCRIPTION_MAX)
+        return tooLong;
+    if (FORBIDDEN_CHAR.test(value))
+        return { problem: '"description" must not contain control, line-break or bidirectional-override characters' };
+    if (!readsSameAlone(raw, value))
+        return singleLine;
+    // Se guarda tal cual lo devuelve YAML: sin trim, con NBSP/BOM intactos.
+    return { value };
 }
 function parseProcessFrontmatter(source, file) {
     let block;
@@ -52,7 +170,22 @@ function parseProcessFrontmatter(source, file) {
     }
     if (block === null)
         return { diagnostics: [] };
-    const { pairs, problems } = readPairs(block);
+    const { pairs, problems, continuations } = readPairs(block);
+    // Un modelo con las claves indentadas no tiene `awm` de nivel superior y se
+    // perdería en silencio como "otro documento". Se nombra solo la línea.
+    // Dispara con el prefiltro barato y, además, si el bloque NO carga como YAML
+    // (sangría parcial o con tab; por encima del tope cuenta como no cargable)
+    // o carga con `awm: process-model` en su nivel superior. Si carga sin `awm`
+    // arriba (mención bajo `metadata:` o dentro de un block scalar), silencio.
+    if (!pairs.has('awm')) {
+        const indentedAwm = continuations.find((c) => INDENTED_DISCRIMINATOR.test(c.text));
+        const loaded = indentedAwm ? loadBlock(block) : undefined;
+        const fires = loaded !== undefined
+            && (loaded.kind !== 'loaded' || (isPlainObject(loaded.doc) && loaded.doc.awm === DISCRIMINATOR));
+        if (indentedAwm && fires) {
+            return { diagnostics: [`${file}: invalid process model — frontmatter keys must not be indented (frontmatter line ${indentedAwm.line})`] };
+        }
+    }
     // Sin discriminador NO es un modelo de proceso: no es un error, es otro
     // documento. Devolver diagnóstico acá inundaría de ruido a todo registry
     // (cada SKILL.md normal caería en esta rama).
@@ -96,6 +229,15 @@ function parseProcessFrontmatter(source, file) {
         if (value !== '' && !DATE.test(value))
             problems.push(`"${field}" must be YYYY-MM-DD`);
     }
+    let description;
+    const rawDescription = pairs.get('description');
+    if (rawDescription !== undefined) {
+        const checked = checkDescription(rawDescription, block, new Set(pairs.keys()));
+        if ('problem' in checked)
+            problems.push(checked.problem);
+        else
+            description = checked.value;
+    }
     if (problems.length > 0) {
         return { diagnostics: [`${file}: invalid process model — ${problems.join('; ')}`] };
     }
@@ -103,6 +245,7 @@ function parseProcessFrontmatter(source, file) {
         model: {
             schema, name, status: status, entryPoint: entryPointRaw === 'true',
             terminatesTo, created: pairs.get('created'), updated: pairs.get('updated'),
+            ...(description !== undefined ? { description } : {}),
         },
         diagnostics: [],
     };

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/commands/process.test.js

@@ -42,6 +42,10 @@ describe('awm process show --json', () => {
         expect(parsed).toEqual(expect.objectContaining({ name: 'mi-proceso', schema: 1, status: 'draft' }));
         expect(parsed.body.routing).toEqual([{ when: 'Al empezar', requiredState: '', goesTo: 'OP-1.1', endsAt: 'SG-1' }]);
     });
+    it('emite description cuando el modelo la trae', () => {
+        const parsed = JSON.parse((0, process_1.runProcessShow)({ models: [model({ description: 'Use when tracing' })], diagnostics: [] }, 'mi-proceso', true).stdout);
+        expect(parsed.description).toBe('Use when tracing');
+    });
     it('el JSON no filtra el path del filesystem del registry', () => {
         const parsed = JSON.parse((0, process_1.runProcessShow)({ models: [model()], diagnostics: [] }, 'mi-proceso', true).stdout);
         expect(JSON.stringify(parsed)).not.toContain('/r/skills');