agentic-workflow-manager 6.5.2 → 8.0.0

package/dist/src/core/ledger/store.js

@@ -12,8 +12,75 @@ exports.archiveLedger = archiveLedger;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
+const types_1 = require("./types");
 const cluster_1 = require("./cluster");
 const LEDGER_DIR = path_1.default.join('.awm', 'ledger');
+function isWithin(root, candidate) {
+    const relative = path_1.default.relative(root, candidate);
+    return relative === '' || (!relative.startsWith(`..${path_1.default.sep}`) && relative !== '..' && !path_1.default.isAbsolute(relative));
+}
+function assertSafeDirectory(directory, root, name) {
+    const stat = fs_1.default.lstatSync(directory);
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        throw new Error(`unsafe ledger ${name} directory`);
+    const real = fs_1.default.realpathSync(directory);
+    if (!isWithin(root, real))
+        throw new Error(`ledger ${name} directory escapes its root`);
+    return real;
+}
+function sourceExists(source) {
+    try {
+        fs_1.default.lstatSync(source);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+function assertSafeLedgerSource(source, ledgerRoot) {
+    const stat = fs_1.default.lstatSync(source);
+    if (stat.isSymbolicLink() || !stat.isFile())
+        throw new Error('unsafe ledger source');
+    const real = fs_1.default.realpathSync(source);
+    if (!isWithin(ledgerRoot, real))
+        throw new Error('ledger source escapes ledger directory');
+}
+function ledgerFilename(branch) {
+    if (typeof branch !== 'string'
+        || branch.length === 0
+        || branch.includes('\\')
+        || path_1.default.posix.isAbsolute(branch)
+        || path_1.default.win32.isAbsolute(branch)
+        || branch.split('/').some(segment => segment === '.' || segment === '..')) {
+        throw new Error('invalid ledger branch');
+    }
+    return branch.replace(/\//g, '__');
+}
+function archiveLabel(label) {
+    if (typeof label !== 'string'
+        || label.length === 0
+        || label === '.'
+        || label.includes('..')
+        || /[/\\]/.test(label)
+        || path_1.default.posix.isAbsolute(label)
+        || path_1.default.win32.isAbsolute(label)) {
+        throw new Error('invalid ledger label');
+    }
+    return label;
+}
+function destinationExists(destination) {
+    try {
+        fs_1.default.lstatSync(destination);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
 function detectBranch(cwd) {
     try {
         const b = (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD', {
@@ -26,28 +93,15 @@ function detectBranch(cwd) {
     }
 }
 function ledgerPath(cwd, branch) {
-    const safe = branch.replace(/\//g, '__');
-    return path_1.default.join(cwd, LEDGER_DIR, `${safe}.jsonl`);
+    return path_1.default.join(cwd, LEDGER_DIR, `${ledgerFilename(branch)}.jsonl`);
 }
 function addEntry(cwd, entry) {
+    const parsed = (0, types_1.parseLedgerEntry)(entry, 'ledger entry');
+    if (!parsed.ok)
+        throw new Error(`invalid ledger entry: ${parsed.reason}`);
     const p = ledgerPath(cwd, entry.branch);
     fs_1.default.mkdirSync(path_1.default.dirname(p), { recursive: true });
-    fs_1.default.appendFileSync(p, JSON.stringify(entry) + '\n', 'utf-8');
-}
-/** Required LedgerEntry fields that `cluster.ts` reads unconditionally
- * (`signature`, `desc`, `ref` when present). A JSONL line can be syntactically
- * valid JSON while still being shape-invalid (e.g. missing `desc`) — that's
- * not a parse error, so it needs its own check, extending the same "skip
- * malformed line" policy this function already applies to JSON syntax errors. */
-function isWellFormedEntry(x) {
-    if (!x || typeof x !== 'object')
-        return false;
-    const e = x;
-    return typeof e.signature === 'string'
-        && typeof e.desc === 'string'
-        && typeof e.branch === 'string'
-        && typeof e.polarity === 'string'
-        && (e.ref === undefined || typeof e.ref === 'string');
+    fs_1.default.appendFileSync(p, JSON.stringify(parsed.entry) + '\n', 'utf-8');
 }
 function listEntries(cwd, branch) {
     const p = ledgerPath(cwd, branch);
@@ -59,9 +113,9 @@ function listEntries(cwd, branch) {
         if (!trimmed)
             continue;
         try {
-            const parsed = JSON.parse(trimmed);
-            if (isWellFormedEntry(parsed))
-                out.push(parsed);
+            const parsed = (0, types_1.parseLedgerEntry)(JSON.parse(trimmed), p);
+            if (parsed.ok)
+                out.push(parsed.entry);
         }
         catch { /* skip malformed line */ }
     }
@@ -71,12 +125,22 @@ function recurring(cwd, branch, min) {
     return (0, cluster_1.clusterEntries)(listEntries(cwd, branch), min);
 }
 function archiveLedger(cwd, branch, label) {
+    const safeLabel = archiveLabel(label);
     const src = ledgerPath(cwd, branch);
-    if (!fs_1.default.existsSync(src))
+    if (!sourceExists(src))
         return false;
-    const safe = branch.replace(/\//g, '__');
-    const dst = path_1.default.join(cwd, LEDGER_DIR, 'archive', `${safe}-${label}.jsonl`);
-    fs_1.default.mkdirSync(path_1.default.dirname(dst), { recursive: true });
+    const safe = ledgerFilename(branch);
+    const projectRoot = fs_1.default.realpathSync(cwd);
+    const ledgerRoot = path_1.default.join(projectRoot, LEDGER_DIR);
+    const safeLedgerRoot = assertSafeDirectory(ledgerRoot, projectRoot, 'root');
+    assertSafeLedgerSource(src, safeLedgerRoot);
+    const archiveRoot = path_1.default.join(ledgerRoot, 'archive');
+    if (!sourceExists(archiveRoot))
+        fs_1.default.mkdirSync(archiveRoot);
+    const safeArchiveRoot = assertSafeDirectory(archiveRoot, safeLedgerRoot, 'archive');
+    const dst = path_1.default.join(safeArchiveRoot, `${safe}-${safeLabel}.jsonl`);
+    if (destinationExists(dst))
+        throw new Error(`ledger archive already exists: ${dst}`);
     fs_1.default.renameSync(src, dst);
     return true;
 }

package/dist/src/core/ledger/types.js

@@ -1,2 +1,56 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFECT_CLASS = void 0;
+exports.parseLedgerEntry = parseLedgerEntry;
+exports.DEFECT_CLASS = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isPolarity(value) {
+    return value === 'win' || value === 'finding';
+}
+function isLedgerClass(value) {
+    return value === 'structural' || value === 'logica' || value === 'proceso' || value === 'seguridad';
+}
+function isSeverity(value) {
+    return value === 'blocker' || value === 'important' || value === 'minor' || value === 'info';
+}
+/** Validates the durable JSONL boundary. Missing defectClass is deliberately legacy-valid. */
+function parseLedgerEntry(input, source) {
+    if (typeof source !== 'string')
+        throw new Error('ledger parse source must be a string');
+    if (!isRecord(input))
+        return { ok: false, source, reason: 'not-object' };
+    if (!isPolarity(input.polarity) || !isLedgerClass(input.class) || !isSeverity(input.severity)) {
+        return { ok: false, source, reason: 'invalid-enum' };
+    }
+    for (const field of ['ts', 'branch', 'phase', 'source_skill', 'signature', 'desc']) {
+        if (typeof input[field] !== 'string')
+            return { ok: false, source, reason: 'invalid-fields' };
+    }
+    if ('ref' in input && input.ref !== undefined && typeof input.ref !== 'string') {
+        return { ok: false, source, reason: 'invalid-ref' };
+    }
+    if ('defectClass' in input && input.defectClass !== undefined
+        && (typeof input.defectClass !== 'string' || !exports.DEFECT_CLASS.test(input.defectClass))) {
+        return { ok: false, source, reason: 'invalid-defect-class' };
+    }
+    return {
+        ok: true,
+        entry: {
+            ts: input.ts,
+            branch: input.branch,
+            phase: input.phase,
+            source_skill: input.source_skill,
+            polarity: input.polarity,
+            class: input.class,
+            signature: input.signature,
+            severity: input.severity,
+            desc: input.desc,
+            ...(typeof input.ref === 'string' ? { ref: input.ref } : {}),
+            // Keep the durable legacy distinction visible to consumers: an older
+            // entry is valid, but has no reusable classification yet.
+            defectClass: typeof input.defectClass === 'string' ? input.defectClass : undefined,
+        },
+    };
+}

package/dist/src/core/paths.js

@@ -174,10 +174,11 @@ function resolveOnPath(bin) {
  * cohorte no llegaba nunca ni a `SERIAL` ni a `ACTIVE`. Un solo bug de comparación, quince
  * tests en cascada.
  *
- * La identidad se toma del filesystem — `(dev, ino)` — que es agnóstica a separadores, a
- * mayúsculas y a nombres cortos. Cuando el volumen no expone inode (`ino === 0`, posible en
- * algunos filesystems de Windows) se cae a `realpathSync.native` — que sí resuelve 8.3 vía
- * la API del SO — normalizando separadores y capitalización.
+ * La identidad se toma primero de `realpathSync.native`, que resuelve la ruta con la API
+ * del SO (incluyendo nombres cortos 8.3) antes de normalizar separadores y capitalización.
+ * En POSIX, dos hard links de archivo conservan el mismo `(dev, ino)` aunque el realpath
+ * mantenga sus nombres distintos; ese fallback preserva su identidad. En Windows no se usa:
+ * dos directorios temporales distintos pueden reportar el mismo par de metadatos.
  *
  * Cualquier fallo de `stat` significa que al menos una no existe: `false`. La identidad
  * nunca se afirma sin prueba.
@@ -192,10 +193,6 @@ function sameExistingPath(a, b) {
     catch {
         return false;
     }
-    // `ino === 0` en AMBOS lados no prueba identidad: probaría que el filesystem no la
-    // reporta. Tratarlo como match haría coincidir dos rutas cualesquiera del mismo volumen.
-    if (sa.ino !== 0 && sb.ino !== 0)
-        return sa.dev === sb.dev && sa.ino === sb.ino;
     const canonical = (p) => {
         try {
             const real = fs_1.default.realpathSync.native(p).replaceAll('\\', '/');
@@ -207,5 +204,9 @@ function sameExistingPath(a, b) {
     };
     const ca = canonical(a);
     const cb = canonical(b);
-    return ca !== null && ca === cb;
+    if (ca === null || cb === null)
+        return false;
+    if (ca === cb)
+        return true;
+    return !isWindowsNative() && sa.ino !== 0 && sb.ino !== 0 && sa.dev === sb.dev && sa.ino === sb.ino;
 }

package/dist/src/core/registries.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REGISTRY_MANIFEST_NAME = exports.CONTENT_DIR_NAMES = void 0;
+exports.REGISTRY_METADATA_FILE_NAMES = exports.REGISTRY_MANIFEST_NAME = exports.REGISTRY_DIR_NAMES = exports.CAPABILITY_DIR_NAMES = exports.CONTENT_DIR_NAMES = void 0;
 exports.registriesDir = registriesDir;
 exports.registriesConfigPath = registriesConfigPath;
 exports.registryContentRoot = registryContentRoot;
@@ -13,7 +13,10 @@ exports.seedBaselineRegistry = seedBaselineRegistry;
 exports.listRegistries = listRegistries;
 exports.contentRoots = contentRoots;
 exports.capabilityRoot = capabilityRoot;
+exports.assertRegularRegistryFile = assertRegularRegistryFile;
+exports.isSafeRegistryRoot = isSafeRegistryRoot;
 exports.validateRegistryLayout = validateRegistryLayout;
+exports.registriesNeedSync = registriesNeedSync;
 exports.syncRegistries = syncRegistries;
 exports.registrySyncErrors = registrySyncErrors;
 exports.describeRegistrySyncErrors = describeRegistrySyncErrors;
@@ -44,9 +47,13 @@ function registriesConfigPath() {
     return path_1.default.join((0, paths_1.awmHome)(), 'registries.json');
 }
 exports.CONTENT_DIR_NAMES = ['skills', 'bundles', 'workflows', 'agents'];
+exports.CAPABILITY_DIR_NAMES = ['hooks', 'sensor-packs'];
+exports.REGISTRY_DIR_NAMES = [...exports.CONTENT_DIR_NAMES, ...exports.CAPABILITY_DIR_NAMES];
+exports.REGISTRY_MANIFEST_NAME = 'awm-registry.json';
+exports.REGISTRY_METADATA_FILE_NAMES = [exports.REGISTRY_MANIFEST_NAME, 'catalog.json'];
 function registryContentRoot(name) {
     const root = path_1.default.join(registriesDir(), name);
-    if (!path_1.default.resolve(root).startsWith(path_1.default.resolve(registriesDir()) + path_1.default.sep)) {
+    if (!name || name === '.' || name.includes('..') || /[/\\]/.test(name) || !path_1.default.resolve(root).startsWith(path_1.default.resolve(registriesDir()) + path_1.default.sep)) {
         throw new Error(`Invalid registry name "${name}" — must not contain path separators`);
     }
     return root;
@@ -68,7 +75,7 @@ function readRegistriesConfig() {
         if (typeof entry?.name !== 'string' || typeof entry?.remote !== 'string') {
             throw new Error(`Invalid registries config at ${registriesConfigPath()}: malformed entry ${JSON.stringify(entry)}`);
         }
-        if (entry.name === '.' || entry.name.includes('/') || entry.name.includes('\\') || entry.name.includes('..')) {
+        if (!entry.name || entry.name === '.' || entry.name.includes('/') || entry.name.includes('\\') || entry.name.includes('..')) {
             throw new Error(`Invalid registries config at ${registriesConfigPath()}: malformed entry name "${entry.name}" (path traversal)`);
         }
     }
@@ -95,7 +102,7 @@ function listRegistries() {
 function contentRoots() {
     const roots = [];
     for (const reg of listRegistries()) {
-        if (fs_1.default.existsSync(reg.contentRoot))
+        if (isSafeRegistryRoot(reg.contentRoot))
             roots.push(reg.contentRoot);
     }
     return roots;
@@ -104,14 +111,121 @@ function contentRoots() {
  *  directorio pedido ('hooks', 'sensor-packs', 'skills'…). null si ninguno. */
 function capabilityRoot(dirName) {
     for (const root of contentRoots()) {
-        if (fs_1.default.existsSync(path_1.default.join(root, dirName)))
+        if (isRegularDirectory(path_1.default.join(root, dirName)))
             return root;
     }
     return null;
 }
-/** Un registry válido tiene ≥1 dir de contenido en su raíz. */
+/** Todo symlink bajo directorios consumidos de un registry es no confiable: discovery,
+ *  hooks y sensores no pueden consumir contenido que podría resolver fuera del clone. */
+function containsManagedSymlink(dir) {
+    let entries;
+    try {
+        entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return true;
+    }
+    for (const entry of entries) {
+        const candidate = path_1.default.join(dir, entry.name);
+        let stat;
+        try {
+            stat = fs_1.default.lstatSync(candidate);
+        }
+        catch {
+            return true;
+        }
+        if (stat.isSymbolicLink())
+            return true;
+        if (stat.isDirectory() && containsManagedSymlink(candidate))
+            return true;
+    }
+    return false;
+}
+function isMissing(error) {
+    return error?.code === 'ENOENT';
+}
+function isRegularDirectory(candidate) {
+    try {
+        const stat = fs_1.default.lstatSync(candidate);
+        return stat.isDirectory() && !stat.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function isSafeOptionalRegistryFile(candidate) {
+    try {
+        const stat = fs_1.default.lstatSync(candidate);
+        return stat.isFile() && !stat.isSymbolicLink();
+    }
+    catch (error) {
+        return isMissing(error);
+    }
+}
+/** Returns false when absent; throws when an existing registry metadata file cannot be
+ * safely read as a regular file. Kept public so catalog and manifest readers share the
+ * same trust boundary instead of relying only on an earlier layout scan. */
+function assertRegularRegistryFile(file) {
+    let stat;
+    try {
+        stat = fs_1.default.lstatSync(file);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw new Error(`Cannot inspect registry metadata at ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (stat.isSymbolicLink())
+        throw new Error(`Registry metadata at ${file} must not be a symbolic link`);
+    if (!stat.isFile())
+        throw new Error(`Registry metadata at ${file} must be a regular file`);
+    return true;
+}
+/** Verifica que la raíz y cada directorio que AWM consume sean regulares y no tengan
+ *  symlinks anidados. Los registries capability-only siguen siendo válidos. */
+function inspectRegistrySafety(root) {
+    if (!isRegularDirectory(root))
+        return { safe: false, hasManagedDirectory: false };
+    let hasManagedDirectory = false;
+    for (const d of exports.REGISTRY_DIR_NAMES) {
+        const candidate = path_1.default.join(root, d);
+        try {
+            const stat = fs_1.default.lstatSync(candidate);
+            if (stat.isSymbolicLink())
+                return { safe: false, hasManagedDirectory: false };
+            if (!stat.isDirectory())
+                continue;
+            hasManagedDirectory = true;
+            if (containsManagedSymlink(candidate))
+                return { safe: false, hasManagedDirectory: false };
+        }
+        catch (error) {
+            if (isMissing(error))
+                continue;
+            return { safe: false, hasManagedDirectory: false };
+        }
+    }
+    for (const file of exports.REGISTRY_METADATA_FILE_NAMES) {
+        if (!isSafeOptionalRegistryFile(path_1.default.join(root, file))) {
+            return { safe: false, hasManagedDirectory: false };
+        }
+    }
+    return { safe: true, hasManagedDirectory };
+}
+function isSafeRegistryRoot(root) {
+    return inspectRegistrySafety(root).safe;
+}
+/** Un registry válido tiene ≥1 directorio de contenido o capability regular y ningún
+ *  symlink en las rutas que AWM consume. */
 function validateRegistryLayout(root) {
-    return exports.CONTENT_DIR_NAMES.some((d) => fs_1.default.existsSync(path_1.default.join(root, d)));
+    const state = inspectRegistrySafety(root);
+    return state.safe && state.hasManagedDirectory;
+}
+/** Whether machine setup must synchronize before any registry-backed discovery.
+ * An empty root is safe to keep configured, but cannot yet supply AWM content. */
+function registriesNeedSync() {
+    return listRegistries().some((registry) => !validateRegistryLayout(registry.contentRoot));
 }
 /** Sincroniza cada registry configurado al ref resuelto (pin > último tag > HEAD);
  *  re-clona si falta el dir. Errores por-registry NO fatales: se reportan en el resultado. */
@@ -120,6 +234,9 @@ async function syncRegistries() {
     for (const reg of listRegistries()) {
         try {
             const freshClone = !fs_1.default.existsSync(reg.contentRoot);
+            if (!freshClone && !isSafeRegistryRoot(reg.contentRoot)) {
+                throw new Error(`Unsafe registry layout at ${reg.contentRoot}`);
+            }
             if (freshClone) {
                 fs_1.default.mkdirSync(registriesDir(), { recursive: true });
                 try {
@@ -140,6 +257,9 @@ async function syncRegistries() {
                 await git.checkout(resolved.ref);
                 if (resolved.kind !== 'tag')
                     await git.pull('origin', resolved.ref);
+                if (!validateRegistryLayout(reg.contentRoot)) {
+                    throw new Error(`Unsafe registry layout at ${reg.contentRoot}`);
+                }
             }
             catch (e) {
                 if (freshClone)
@@ -169,13 +289,14 @@ function describeRegistrySyncErrors(errors) {
     return errors.map((e) => `${e.name}: ${e.error}`).join('; ');
 }
 /**
- * Registries that both errored during sync AND have no content on disk
- * afterwards — i.e. genuinely unusable, as opposed to merely stale.
+ * Registries that both errored during sync AND no longer have a usable content
+ * layout afterwards — i.e. genuinely unusable, as opposed to merely stale.
  *
  * `syncRegistries()` deliberately reports per-registry failures as results
  * rather than throwing, so a flaky secondary registry never aborts a whole
  * run. Callers that go on to READ registry content (init) still need to know
- * whether what they are about to read exists: otherwise a missing registry
+ * whether what they are about to read remains usable: otherwise a missing,
+ * empty, or unsafe registry
  * resurfaces much later as an unrelated step's failure, with its real cause
  * already discarded. Note that "usable" is deliberately about content on disk,
  * not about being a healthy git clone — a seeded content root with no `.git`
@@ -188,7 +309,7 @@ function unusableSyncedRegistries(results) {
     const roots = new Map(listRegistries().map((r) => [r.name, r.contentRoot]));
     return errors.filter((e) => {
         const root = roots.get(e.name);
-        return root === undefined || !fs_1.default.existsSync(root);
+        return root === undefined || !validateRegistryLayout(root);
     });
 }
 /** `unusableSyncedRegistries` as a guard: throws naming every unusable registry. */
@@ -196,12 +317,11 @@ function assertSyncedRegistriesUsable(results) {
     const unusable = unusableSyncedRegistries(results);
     if (unusable.length === 0)
         return;
-    throw new Error(`registry sync failed and left no content on disk — ${describeRegistrySyncErrors(unusable)}`);
+    throw new Error(`registry sync failed and left no usable content on disk — ${describeRegistrySyncErrors(unusable)}`);
 }
-exports.REGISTRY_MANIFEST_NAME = 'awm-registry.json';
 function readRegistryManifest(root) {
     const file = path_1.default.join(root, exports.REGISTRY_MANIFEST_NAME);
-    if (!fs_1.default.existsSync(file))
+    if (!assertRegularRegistryFile(file))
         return { overrides: new Set() };
     let raw;
     try {

package/dist/src/index.js

@@ -118,6 +118,15 @@ program.command('add [name]')
         if (r.action === 'error')
             console.warn(picocolors_1.default.yellow(`  ⚠  registry ${r.name}: ${r.error}`));
     }
+    try {
+        (0, registries_1.assertSyncedRegistriesUsable)(results);
+    }
+    catch (e) {
+        s.stop('Registry sync failed.');
+        console.error(picocolors_1.default.red(e.message));
+        process.exitCode = 1;
+        return;
+    }
     // 1b. If `name` matches a bundle, run the bundle-activation flow and exit.
     if (name) {
         const allBundles = (0, bundles_1.discoverAllBundles)();
@@ -437,6 +446,14 @@ program.command('list [package]')
         if (r.action === 'error')
             console.warn(picocolors_1.default.yellow(`  ⚠  registry ${r.name}: ${r.error}`));
     }
+    try {
+        (0, registries_1.assertSyncedRegistriesUsable)(listSyncResults);
+    }
+    catch (e) {
+        console.error(picocolors_1.default.red(e.message));
+        process.exitCode = 1;
+        return;
+    }
     const fullView = (0, registry_view_1.buildPackageView)((0, discovery_1.discoverSkills)(), (0, discovery_1.discoverWorkflows)(), (0, discovery_1.discoverAgents)(), (0, bundles_1.discoverAllBundles)());
     const view = options.all ? fullView : fullView.filter((p) => p.visibility !== 'private');
     if (view.length === 0) {
@@ -716,4 +733,10 @@ miroCmd.command('sync <storyMapPath>')
 (0, job_1.registerJobCommand)(program);
 (0, watch_1.registerWatchCommand)(program);
 (0, track_1.registerTrackCommand)(program);
-program.parse();
+// Commander only waits for async action handlers through parseAsync().  The CLI has
+// async commands (including `sensors coverage`), so returning its promise keeps the
+// process alive until their JSON/output contract has been completed.
+program.parseAsync().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/tests/commands/ledger/index.test.js

@@ -40,6 +40,17 @@ describe('awm ledger CLI', () => {
         expect(entries[0]).toMatchObject({ signature: 'sig-1', polarity: 'finding', class: 'logica' });
         expect(entries[0].ts).toMatch(/\d{4}-\d{2}-\d{2}T/);
     });
+    test('add persists an optional reusable defect class', () => {
+        run(['add', '--branch', 'feat-x', '--polarity', 'finding', '--class', 'logica',
+            '--signature', 'sig-1', '--severity', 'blocker', '--desc', 'boom', '--defect-class', 'lint-errors'], cwd);
+        expect((0, store_1.listEntries)(cwd, 'feat-x')).toEqual([expect.objectContaining({ defectClass: 'lint-errors' })]);
+    });
+    test.each(['', 'Bad_ID', '../escape', 'a b', '-leading', 'trailing-'])('add rejects invalid defect class %p before writing', (defectClass) => {
+        expect(() => run(['add', '--branch', 'feat-x', '--polarity', 'finding', '--class', 'logica',
+            '--signature', 'sig-1', '--severity', 'blocker', '--desc', 'boom', '--defect-class', defectClass], cwd))
+            .toThrow(/defect-class.*kebab-case/i);
+        expect((0, store_1.listEntries)(cwd, 'feat-x')).toEqual([]);
+    });
     test('list emits the branch entries as JSON', () => {
         run(['add', '--branch', 'feat-x', '--polarity', 'win', '--class', 'proceso',
             '--signature', 'good', '--severity', 'info', '--desc', 'nice'], cwd);