agentic-workflow-manager 6.4.1 → 6.5.0

package/dist/src/commands/sensors/coverage/resolve.js

@@ -0,0 +1,126 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readBoundedJson = readBoundedJson;
+exports.resolveCoverageInputs = resolveCoverageInputs;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const registries_1 = require("../../../core/registries");
+const contract_1 = require("./contract");
+function readFailure(file, error) {
+    return new Error(`Cannot read ${file}: ${error instanceof Error ? error.message : String(error)}`);
+}
+/** Read JSON from a regular, bounded file without ever following a symlink. */
+function readBoundedJson(file) {
+    if (typeof file !== 'string' || file.trim().length === 0)
+        throw new Error('readBoundedJson: file must be a non-empty string');
+    let listed;
+    try {
+        listed = fs_1.default.lstatSync(file);
+    }
+    catch (error) {
+        throw readFailure(file, error);
+    }
+    if (!listed.isFile() || listed.isSymbolicLink())
+        throw new Error(`Cannot read ${file}: expected a regular file`);
+    if (listed.size > contract_1.MAX_COVERAGE_FILE_BYTES)
+        throw new Error(`Cannot read ${file}: exceeds 1 MiB limit`);
+    const noFollow = fs_1.default.constants.O_NOFOLLOW;
+    if (typeof noFollow !== 'number')
+        throw new Error(`Cannot read ${file}: platform cannot guarantee no symlink dereference`);
+    let descriptor;
+    let content;
+    try {
+        descriptor = fs_1.default.openSync(file, fs_1.default.constants.O_RDONLY | noFollow);
+        const opened = fs_1.default.fstatSync(descriptor);
+        if (!opened.isFile() || opened.size > contract_1.MAX_COVERAGE_FILE_BYTES) {
+            throw new Error('expected a regular file within the 1 MiB limit');
+        }
+        const buffer = Buffer.allocUnsafe(contract_1.MAX_COVERAGE_FILE_BYTES + 1);
+        const count = fs_1.default.readSync(descriptor, buffer, 0, buffer.length, null);
+        if (!Number.isSafeInteger(count) || count < 0 || count > contract_1.MAX_COVERAGE_FILE_BYTES) {
+            throw new Error('exceeds 1 MiB limit');
+        }
+        content = buffer.subarray(0, count).toString('utf8');
+    }
+    catch (error) {
+        throw readFailure(file, error);
+    }
+    finally {
+        if (descriptor !== undefined)
+            fs_1.default.closeSync(descriptor);
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON at ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function readPackEnvelope(input, file, expectedName) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input))
+        throw new Error(`Invalid pack at ${file}: expected object`);
+    const pack = input;
+    if (typeof pack.name !== 'string' || pack.name !== expectedName) {
+        throw new Error(`Invalid pack at ${file}: name must equal '${expectedName}'`);
+    }
+    if (typeof pack.sensors !== 'object' || pack.sensors === null || Array.isArray(pack.sensors)) {
+        throw new Error(`Invalid pack at ${file}: sensors must be an object`);
+    }
+    return 'coverage' in pack ? { coverage: pack.coverage } : {};
+}
+function safeRegistryName(name) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) || name.includes('..')) {
+        throw new Error(`Invalid registry name '${name}': expected a safe path component`);
+    }
+}
+/** Finds the nearest manifest without following a symlink during discovery. */
+function findManifestDirNoFollow(startCwd) {
+    let dir = path_1.default.resolve(startCwd);
+    while (true) {
+        const manifestPath = path_1.default.join(dir, '.awm', 'sensors.json');
+        try {
+            fs_1.default.lstatSync(manifestPath);
+            return dir;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw readFailure(manifestPath, error);
+        }
+        const parent = path_1.default.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function resolveCoverageInputs(cwd) {
+    if (typeof cwd !== 'string' || cwd.trim().length === 0)
+        throw new Error('resolveCoverageInputs: cwd must be a non-empty string');
+    const projectRoot = findManifestDirNoFollow(cwd);
+    if (!projectRoot)
+        return { kind: 'not_configured' };
+    const manifestPath = path_1.default.join(projectRoot, '.awm', 'sensors.json');
+    const manifest = (0, contract_1.parseCoverageManifest)(readBoundedJson(manifestPath), manifestPath);
+    for (const registry of (0, registries_1.listRegistries)()) {
+        safeRegistryName(registry.name);
+        const packPath = path_1.default.join(registry.contentRoot, 'sensor-packs', manifest.pack, 'pack.json');
+        try {
+            fs_1.default.lstatSync(packPath);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw readFailure(packPath, error);
+        }
+        const { coverage } = readPackEnvelope(readBoundedJson(packPath), packPath, manifest.pack);
+        if (coverage === undefined)
+            return { kind: 'no_reference', projectRoot, pack: manifest.pack, registry: registry.name, manifest };
+        return {
+            kind: 'ready', projectRoot, pack: manifest.pack, registry: registry.name,
+            manifest, contract: (0, contract_1.parseCoverageContract)(coverage, packPath),
+        };
+    }
+    throw new Error(`Pack '${manifest.pack}' was not found in configured registries`);
+}

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

@@ -12,6 +12,8 @@ const init_1 = require("./init");
 const status_1 = require("./status");
 const install_1 = require("./install");
 const baseline_1 = require("./baseline");
+const coverage_1 = require("./coverage");
+const render_1 = require("./coverage/render");
 const registries_1 = require("../../core/registries");
 /** Map a sensor run verdict to a process exit code. fail → 1; everything else → 0.
  *  not_certified intentionally exits 0: its signal lives in `overall`, because
@@ -21,6 +23,20 @@ function exitCodeFor(output) {
 }
 function registerSensorsCommand(program) {
     const sensors = program.command('sensors').description('manage computational sensors for the current project');
+    sensors
+        .command('coverage')
+        .description('report static gaps between configured sensors and the pack reference')
+        .option('--json', 'emit the versioned machine-readable envelope')
+        .action((opts) => {
+        try {
+            const report = (0, coverage_1.runCoverage)(process.cwd());
+            process.stdout.write(opts.json ? (0, render_1.renderCoverageJson)(report) : (0, render_1.renderCoverageHuman)(report));
+        }
+        catch (error) {
+            prompts_1.log.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
     sensors
         .command('run')
         .description('run sensors from .awm/sensors.json')

package/dist/src/core/provider-version.js

@@ -4,6 +4,7 @@ exports.assertProviderSupported = assertProviderSupported;
 const child_process_1 = require("child_process");
 const providers_1 = require("../providers");
 const versioning_1 = require("./versioning");
+const paths_1 = require("./paths");
 function assertProviderSupported(agent, exec = child_process_1.execFileSync) {
     const provider = (0, providers_1.providerFor)(agent);
     if (!provider.versionCommand || !provider.minimumVersion) {
@@ -15,17 +16,40 @@ function assertProviderSupported(agent, exec = child_process_1.execFileSync) {
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'pipe'],
             timeout: 5000,
+            // Windows can't CreateProcess a `.cmd` shim directly (npm installs
+            // `codex` as `codex.cmd`, not `codex.exe`) — execFileSync needs a
+            // shell to resolve and run it, or it throws ENOENT even though
+            // typing `codex --version` in the same shell works fine. Safe here
+            // (unlike sensors.json's `cmd`, core/paths.ts's resolveOnPath):
+            // `provider.versionCommand.command`/`args` are hardcoded first-party
+            // config (providers/index.ts), never attacker-controlled input.
+            // Found running the issue #55 Windows playbook: `awm init -a codex`
+            // reported "Codex is not installed" on a machine where it plainly
+            // was — `codex --version` worked fine typed directly.
+            shell: (0, paths_1.isWindowsNative)(),
         }).toString();
     }
     catch (error) {
-        const code = error.code;
+        const err = error;
         // `provider.label` y `versionCommand`, no "Codex" literal. Esta funcion es
         // generica sobre AgentTarget desde siempre, pero cada mensaje y el patron de
         // parseo nombraban al unico provider que hoy declara `versionCommand` — el
         // segundo en declararlo habria reportado "Codex no esta instalado" al no
         // encontrar SU binario, y habria fallado a parsear una salida perfectamente
         // valida contra el formato de otro programa.
-        if (code === 'ENOENT') {
+        //
+        // Two distinct "not found" shapes to catch now that Windows goes through
+        // a shell (see `shell: isWindowsNative()` above): without a shell, a
+        // missing binary is a spawn-level ENOENT; through cmd.exe, the shell
+        // itself spawns fine and the missing command instead surfaces as a
+        // non-zero exit with "'codex' is not recognized..." on stderr — no
+        // ENOENT anywhere. Missing this second shape was a real regression:
+        // windows-latest CI (no codex installed at all) started reporting
+        // "version probe failed" instead of "not installed", because the exit
+        // code alone doesn't say WHY the shell failed.
+        const shellCommandNotFound = (0, paths_1.isWindowsNative)()
+            && /is not recognized as an internal or external command/i.test(String(err.stderr ?? ''));
+        if (err.code === 'ENOENT' || shellCommandNotFound) {
             throw new Error(`${provider.label} is not installed or not available on PATH ` +
                 `(tried \`${provider.versionCommand.command}\`). Install it, then re-run.`);
         }

package/dist/src/index.js

@@ -122,7 +122,7 @@ program.command('add [name]')
     if (name) {
         const allBundles = (0, bundles_1.discoverAllBundles)();
         const prefs = (0, config_1.getPreferences)();
-        const outcome = (0, add_1.runAddBundleCore)({ name, agent: options.agent, scope: options.scope }, prefs, allBundles);
+        const outcome = (0, add_1.runAddBundleCore)({ name, agent: options.agent, scope: options.scope, method: options.method }, prefs, allBundles);
         if (outcome.code !== 0)
             process.exit(outcome.code);
         (0, prompts_1.outro)('Done.');
@@ -534,12 +534,17 @@ program.command('remove [name]')
         targetAgents = agentChoice;
     }
     let scopeVal;
-    if (options.scope) {
-        if (options.scope !== 'local' && options.scope !== 'global') {
-            console.error(picocolors_1.default.red(`Invalid scope "${options.scope}". Use: local or global.`));
+    if (options.scope || options.yes) {
+        // Same reasoning as the --agent default just above: `--yes` means ZERO
+        // prompts. Without the `options.yes` half of this condition, `awm remove
+        // <bundle> --yes` still opened the scope picker and hung any
+        // non-interactive caller — the flag promised no-interactive and wasn't.
+        const resolved = (0, config_1.resolveScopeOption)(options.scope, prefs.defaultScope);
+        if (!resolved.ok) {
+            console.error(picocolors_1.default.red(resolved.error));
             process.exit(1);
         }
-        scopeVal = options.scope;
+        scopeVal = resolved.scope;
     }
     else {
         const scopeChoice = await (0, prompts_1.select)({

package/dist/src/utils/config.js

@@ -9,6 +9,7 @@ exports.getPreferences = getPreferences;
 exports.loadPreferences = loadPreferences;
 exports.savePreferences = savePreferences;
 exports.enableAgent = enableAgent;
+exports.resolveScopeOption = resolveScopeOption;
 // src/utils/config.ts
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -158,3 +159,19 @@ function enableAgent(prefs, agent) {
         ? prefs
         : { ...prefs, enabledAgents: [...prefs.enabledAgents, agent] };
 }
+/**
+ * Resolve `--scope` the same way across every non-interactive command path: an
+ * explicit value wins (validated), otherwise fall back to the caller's default
+ * instead of prompting. Pulled out of `remove`'s Commander closure (D-006) after
+ * `--yes` was found to still open the scope picker with no `--scope` given —
+ * `--yes` means zero prompts, and this is the one call site that had drifted
+ * from that rule (the sibling --agent default sits right next to it in index.ts).
+ */
+function resolveScopeOption(explicit, fallback) {
+    if (explicit === undefined)
+        return { ok: true, scope: fallback };
+    if (explicit !== 'local' && explicit !== 'global') {
+        return { ok: false, error: `Invalid scope "${explicit}". Use: local or global.` };
+    }
+    return { ok: true, scope: explicit };
+}

package/dist/tests/commands/add.test.js

@@ -94,3 +94,45 @@ it('awm add demo materializes a real Copilot .instructions.md file end-to-end',
     fs_1.default.rmSync(content, { recursive: true, force: true });
     fs_1.default.rmSync(projectRoot, { recursive: true, force: true });
 });
+// Regression for WIN-02 (issue #55 Windows playbook): `--method copy` was
+// silently discarded by this exact function — `runAddBundleCore` hardcoded
+// 'symlink' regardless of what the CLI parsed, so a real Windows machine got
+// a Junction back no matter what `--method` asked for.
+describe('runAddBundleCore --method', () => {
+    const claudeCodePrefs = {
+        defaultAgent: 'claude-code', enabledAgents: ['claude-code'], installMethod: 'symlink', defaultScope: 'local',
+    };
+    it('honours an explicit --method copy: a real directory, not a symlink', () => {
+        const content = makeContentFixture();
+        const projectRoot = makeProjectRoot();
+        const bundles = (0, bundles_1.discoverBundles)(content);
+        const outcome = (0, add_1.runAddBundleCore)({ name: 'demo', agent: 'claude-code', method: 'copy', cwd: projectRoot }, claudeCodePrefs, bundles);
+        expect(outcome.code).toBe(0);
+        const skillPath = path_1.default.join(projectRoot, '.claude/skills/demo-skill');
+        expect(fs_1.default.lstatSync(skillPath).isSymbolicLink()).toBe(false);
+        expect(fs_1.default.readFileSync(path_1.default.join(skillPath, 'SKILL.md'), 'utf8')).toContain('Follow the demo skill body.');
+        fs_1.default.rmSync(content, { recursive: true, force: true });
+        fs_1.default.rmSync(projectRoot, { recursive: true, force: true });
+    });
+    it('still defaults to symlink when --method is omitted (unchanged behavior)', () => {
+        const content = makeContentFixture();
+        const projectRoot = makeProjectRoot();
+        const bundles = (0, bundles_1.discoverBundles)(content);
+        const outcome = (0, add_1.runAddBundleCore)({ name: 'demo', agent: 'claude-code', cwd: projectRoot }, claudeCodePrefs, bundles);
+        expect(outcome.code).toBe(0);
+        const skillPath = path_1.default.join(projectRoot, '.claude/skills/demo-skill');
+        expect(fs_1.default.lstatSync(skillPath).isSymbolicLink()).toBe(true);
+        fs_1.default.rmSync(content, { recursive: true, force: true });
+        fs_1.default.rmSync(projectRoot, { recursive: true, force: true });
+    });
+    it('rejects an invalid --method value without touching the filesystem', () => {
+        const content = makeContentFixture();
+        const projectRoot = makeProjectRoot();
+        const bundles = (0, bundles_1.discoverBundles)(content);
+        const outcome = (0, add_1.runAddBundleCore)({ name: 'demo', agent: 'claude-code', method: 'bogus', cwd: projectRoot }, claudeCodePrefs, bundles);
+        expect(outcome.code).toBe(1);
+        expect(fs_1.default.existsSync(path_1.default.join(projectRoot, '.claude/skills/demo-skill'))).toBe(false);
+        fs_1.default.rmSync(content, { recursive: true, force: true });
+        fs_1.default.rmSync(projectRoot, { recursive: true, force: true });
+    });
+});

package/dist/tests/commands/init.test.js

@@ -108,6 +108,29 @@ describe('runInit', () => {
             const caveatCalls = logSpy.mock.calls.filter((c) => /awm watch/i.test(String(c[0])));
             expect(caveatCalls).toHaveLength(0);
         });
+        // Regression: `awm init --yes --json > init.json` on native Windows used to
+        // write the caveat to stdout via console.log AHEAD of the JSON payload,
+        // so the documented core-acceptance.md CORE-03 flow produced a file that
+        // wasn't valid JSON (banner text, then `{...}`). The caveat must still
+        // reach the operator — it now goes to stderr instead of vanishing.
+        it('does not pollute --json stdout with the caveat on native Windows', async () => {
+            Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+            const errSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+            const { runInit } = require('../../src/commands/init');
+            await runInit({
+                cwd: tmpHome,
+                yes: true,
+                json: true,
+                actions: { syncCache: async () => { }, installHook: () => ({ status: 'installed' }) },
+            });
+            const written = writeSpy.mock.calls.map((c) => c[0]).join('');
+            expect(() => JSON.parse(written)).not.toThrow();
+            const caveatOnStdout = logSpy.mock.calls.filter((c) => /awm watch/i.test(String(c[0])));
+            expect(caveatOnStdout).toHaveLength(0);
+            const caveatOnStderr = errSpy.mock.calls.filter((c) => /awm watch/i.test(String(c[0])));
+            expect(caveatOnStderr).toHaveLength(1);
+            errSpy.mockRestore();
+        });
     });
     it('returns exit 0 on a bare HOME and never prompts with --yes (cache stubbed)', async () => {
         const { runInit } = require('../../src/commands/init');

package/dist/tests/commands/sensors/coverage/contract.test.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const contract_1 = require("../../../../src/commands/sensors/coverage/contract");
+describe('coverage contract v1', () => {
+    it('returns a complete valid contract unchanged', () => {
+        const input = {
+            schemaVersion: 1,
+            classes: {
+                'runtime-validation': {
+                    description: 'All durable coverage artifacts validate their inputs.',
+                    detectors: [{
+                            sensor: 'contract-test',
+                            evidence: {
+                                commandIncludes: ['coverage'],
+                                files: [{ path: 'contract.ts', containsAll: ['parseCoverageContract'] }],
+                            },
+                        }],
+                    remedy: { summary: 'Add a parser.', command: 'npm test -- contract.test.ts' },
+                },
+            },
+        };
+        expect((0, contract_1.parseCoverageContract)(input, 'coverage.json')).toEqual(input);
+    });
+    test.each([
+        [{ schemaVersion: 2, classes: {} }, 'schemaVersion'],
+        [{ schemaVersion: 1, classes: {}, extra: true }, 'unknown field'],
+        [{ schemaVersion: 1, classes: {} }, 'classes'],
+        [{ schemaVersion: 1, classes: { Bad: { description: 'x', detectors: [{ sensor: 'test' }], remedy: { summary: 'x', command: 'x' } } } }, 'class'],
+        [{ schemaVersion: 1, classes: { valid: { description: '', detectors: [{ sensor: 'test' }], remedy: { summary: 'x', command: 'x' } } } }, 'description'],
+        [{ schemaVersion: 1, classes: { valid: { description: '  \t', detectors: [{ sensor: 'test' }], remedy: { summary: 'x', command: 'x' } } } }, 'description'],
+        [{ schemaVersion: 1, classes: { valid: { description: 'x', detectors: [], remedy: { summary: 'x', command: 'x' } } } }, 'detectors'],
+    ])('rejects malformed contract %j', (input, message) => {
+        expect(() => (0, contract_1.parseCoverageContract)(input, 'coverage.json')).toThrow(message);
+    });
+    test.each(['', '.', '..', '../secret', 'a/../../secret', '/etc/passwd', 'C:\\secret', 'a\\..\\secret', ' report.txt', 'report!.txt'])('rejects hostile evidence path %p', (path) => {
+        const input = {
+            schemaVersion: 1,
+            classes: {
+                valid: {
+                    description: 'x',
+                    detectors: [{ sensor: 'test', evidence: { files: [{ path, containsAll: [] }] } }],
+                    remedy: { summary: 'x', command: 'x' },
+                },
+            },
+        };
+        expect(() => (0, contract_1.parseCoverageContract)(input, 'coverage.json')).toThrow('path');
+    });
+    it('rejects whitespace-only evidence text', () => {
+        const input = {
+            schemaVersion: 1,
+            classes: {
+                valid: {
+                    description: 'x',
+                    detectors: [{ sensor: 'test', evidence: { files: [{ path: 'report.txt', containsAll: [' \n'] }] } }],
+                    remedy: { summary: 'x', command: 'x' },
+                },
+            },
+        };
+        expect(() => (0, contract_1.parseCoverageContract)(input, 'coverage.json')).toThrow('containsAll');
+    });
+    it('rejects unknown nested evidence fields', () => {
+        const input = {
+            schemaVersion: 1,
+            classes: {
+                valid: {
+                    description: 'x',
+                    detectors: [{ sensor: 'test', evidence: { commandInclude: ['coverage'] } }],
+                    remedy: { summary: 'x', command: 'x' },
+                },
+            },
+        };
+        expect(() => (0, contract_1.parseCoverageContract)(input, 'coverage.json')).toThrow('unknown field');
+    });
+});
+describe('coverage manifest boundary', () => {
+    it('accepts all legacy sensor fields', () => {
+        const input = {
+            pack: 'js-ts',
+            concurrency: 2,
+            sensors: {
+                lint: {
+                    cmd: 'npm run lint', fast: true, enabled: true, timeout: 120, changedCmd: 'npm run lint -- {files}', changedExtensions: ['.ts'], formatter: 'eslint-llm',
+                },
+            },
+        };
+        expect((0, contract_1.parseCoverageManifest)(input, 'sensors.json')).toEqual(input);
+    });
+    test.each([
+        [null, 'object'],
+        [{}, 'pack'],
+        [{ pack: '', sensors: {} }, 'pack'],
+        [{ pack: ' js-ts', sensors: {} }, 'pack'],
+        [{ pack: 'js ts', sensors: {} }, 'pack'],
+        [{ pack: 'js@ts', sensors: {} }, 'pack'],
+        [{ pack: 'js-ts', sensors: null }, 'sensors'],
+        [{ pack: 'js-ts', sensors: { lint: { cmd: 3 } } }, 'cmd'],
+        [{ pack: 'js-ts', sensors: { 'lint!': {} } }, 'sensor name'],
+    ])('rejects malformed manifest %j', (input, message) => {
+        expect(() => (0, contract_1.parseCoverageManifest)(input, 'sensors.json')).toThrow(message);
+    });
+});

package/dist/tests/commands/sensors/coverage/evaluate.test.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const evaluate_1 = require("../../../../src/commands/sensors/coverage/evaluate");
+const contract = {
+    schemaVersion: 1,
+    classes: {
+        alpha: {
+            description: 'Alpha',
+            detectors: [{ sensor: 'one' }, { sensor: 'two' }],
+            remedy: { summary: 'Fix alpha', command: 'fix alpha' },
+        },
+        zeta: {
+            description: 'Zeta',
+            detectors: [{ sensor: 'three' }],
+            remedy: { summary: 'Fix zeta', command: 'fix zeta' },
+        },
+    },
+};
+const observation = (classId, detectorIndex, sensor, status) => ({ classId, detectorIndex, sensor, status, evidence: [] });
+describe('coverage evaluation', () => {
+    test.each([
+        [[observation('alpha', 0, 'one', 'covered'), observation('alpha', 1, 'two', 'missing')], 'covered'],
+        [[observation('alpha', 0, 'one', 'missing'), observation('alpha', 1, 'two', 'disabled')], 'missing'],
+        [[observation('alpha', 0, 'one', 'ineffective'), observation('alpha', 1, 'two', 'missing')], 'missing'],
+        [[observation('alpha', 0, 'one', 'unverifiable'), observation('alpha', 1, 'two', 'missing')], 'unverifiable'],
+    ])('reduces detector alternatives %j to %s', (alpha, expected) => {
+        const result = (0, evaluate_1.evaluateCoverage)(contract, [...alpha, observation('zeta', 0, 'three', 'covered')]);
+        expect(result.classes.find((item) => item.id === 'alpha')?.status).toBe(expected);
+    });
+    it('makes global gaps outrank unverifiable while preserving both classes', () => {
+        const result = (0, evaluate_1.evaluateCoverage)(contract, [
+            observation('alpha', 0, 'one', 'unverifiable'),
+            observation('alpha', 1, 'two', 'missing'),
+            observation('zeta', 0, 'three', 'missing'),
+        ]);
+        expect(result.overall).toBe('gaps');
+        expect(result.classes.map((item) => [item.id, item.status])).toEqual([
+            ['alpha', 'unverifiable'],
+            ['zeta', 'missing'],
+        ]);
+    });
+    it('sorts classes by stable ID and is deterministic under reordered observations', () => {
+        const result = (0, evaluate_1.evaluateCoverage)(contract, [
+            observation('zeta', 0, 'three', 'covered'),
+            observation('alpha', 1, 'two', 'missing'),
+            observation('alpha', 0, 'one', 'covered'),
+        ]);
+        expect(result.classes.map((item) => item.id)).toEqual(['alpha', 'zeta']);
+        expect((0, evaluate_1.evaluateCoverage)(contract, [
+            observation('alpha', 0, 'one', 'covered'),
+            observation('zeta', 0, 'three', 'covered'),
+            observation('alpha', 1, 'two', 'missing'),
+        ])).toEqual(result);
+    });
+    it('fails loudly when an observation is missing or duplicated', () => {
+        expect(() => (0, evaluate_1.evaluateCoverage)(contract, [])).toThrow(/missing observation.*one/);
+        expect(() => (0, evaluate_1.evaluateCoverage)(contract, [
+            observation('alpha', 0, 'one', 'covered'),
+            observation('alpha', 0, 'one', 'covered'),
+            observation('alpha', 1, 'two', 'covered'),
+            observation('zeta', 0, 'three', 'covered'),
+        ])).toThrow(/duplicate observation.*alpha:0/);
+    });
+    it('keeps alternatives with the same sensor independent by detector index', () => {
+        const sameSensor = {
+            schemaVersion: 1,
+            classes: {
+                config: {
+                    description: 'Project configuration',
+                    detectors: [{ sensor: 'lint' }, { sensor: 'lint' }],
+                    remedy: { summary: 'Add config', command: 'touch eslint.config.js' },
+                },
+            },
+        };
+        const result = (0, evaluate_1.evaluateCoverage)(sameSensor, [
+            observation('config', 0, 'lint', 'ineffective'),
+            observation('config', 1, 'lint', 'covered'),
+        ]);
+        expect(result.classes[0].status).toBe('covered');
+        expect(result.classes[0].detectors).toHaveLength(2);
+    });
+});