agentic-workflow-manager 6.5.2 → 8.0.0

package/dist/tests/integration/sensor-coverage.e2e.test.js

@@ -14,6 +14,7 @@ const fixture = path_1.default.join(cliDir, 'tests/fixtures/sensor-coverage/js-t
 const registryFixture = path_1.default.join(cliDir, 'tests/fixtures/sensor-coverage/registry');
 const noFollowUnavailableOnNativeWindows = process.platform === 'win32'
     && typeof fs_1.default.constants.O_NOFOLLOW !== 'number';
+const testWithNoFollow = noFollowUnavailableOnNativeWindows ? test.skip : test;
 const hashTree = (root) => {
     const hash = crypto_1.default.createHash('sha256');
     const walk = (directory) => {
@@ -63,7 +64,7 @@ function runWithFixture(mutatePack) {
     }
     return { tmp, project, awmHome };
 }
-test('compiled CLI reports gaps or fails closed when no-follow safety is unavailable (RF-1.1, RF-1.4)', () => {
+test('compiled CLI reports static and read-only empirical coverage without leaking ledger text (R5.6, R5.10)', () => {
     const { tmp, project, awmHome } = runWithFixture();
     try {
         const before = [hashTree(project), hashTree(awmHome)];
@@ -78,9 +79,16 @@ test('compiled CLI reports gaps or fails closed when no-follow safety is unavail
             expect(result.status).toBe(0);
             const report = JSON.parse(result.stdout ?? '');
             expect(report.static.classes).toEqual(expect.arrayContaining([
-                expect.objectContaining({ id: 'formatting', status: 'missing' }),
-                expect.objectContaining({ id: 'project-style-conventions', status: 'missing' }),
+                expect.objectContaining({ id: 'formatting', status: 'unverifiable' }),
+                expect.objectContaining({ id: 'project-style-conventions', status: 'unverifiable' }),
             ]));
+            expect(report).toMatchObject({ schemaVersion: 2, empirical: {
+                    status: 'partial', classes: [expect.objectContaining({ defectClass: 'lint-errors', occurrences: 2, recurrent: true })],
+                    unclassified: { occurrences: 1 },
+                } });
+            expect(result.stdout).not.toContain('fixture-secret-description');
+            expect(result.stdout).not.toContain('private-lint-signature');
+            expect(result.stdout).not.toContain('windows secret');
         }
         expect([hashTree(project), hashTree(awmHome)]).toEqual(before);
     }
@@ -88,7 +96,25 @@ test('compiled CLI reports gaps or fails closed when no-follow safety is unavail
         fs_1.default.rmSync(tmp, { recursive: true, force: true });
     }
 });
-const testWithNoFollow = noFollowUnavailableOnNativeWindows ? test.skip : test;
+testWithNoFollow('compiled coverage keeps static verdict stable while --min changes only recurrence emphasis', () => {
+    const { tmp, project, awmHome } = runWithFixture();
+    try {
+        const before = [hashTree(project), hashTree(awmHome)];
+        const run = (min) => (0, child_process_1.spawnSync)(process.execPath, [bin, 'sensors', 'coverage', '--json', '--min', min], {
+            cwd: project, encoding: 'utf8', env: { ...process.env, AWM_HOME: awmHome, AWM_NO_UPDATE_CHECK: '1' },
+        });
+        const defaultReport = JSON.parse(run('2').stdout ?? '');
+        const minThree = JSON.parse(run('3').stdout ?? '');
+        expect(defaultReport.static).toEqual(minThree.static);
+        expect(defaultReport.overall).toBe(minThree.overall);
+        expect(defaultReport.empirical.classes[0]).toMatchObject({ occurrences: 2, recurrent: true });
+        expect(minThree.empirical.classes[0]).toMatchObject({ occurrences: 2, recurrent: false });
+        expect([hashTree(project), hashTree(awmHome)]).toEqual(before);
+    }
+    finally {
+        fs_1.default.rmSync(tmp, { recursive: true, force: true });
+    }
+});
 testWithNoFollow('informative states exit zero; malformed contract exits non-zero (R2.7, R2.9)', () => {
     const run = (mutatePack) => {
         const { tmp, project, awmHome } = runWithFixture(mutatePack);
@@ -105,9 +131,12 @@ testWithNoFollow('informative states exit zero; malformed contract exits non-zer
     const noReference = run((pack) => { delete pack.coverage; });
     const malformed = run((pack) => { pack.coverage.schemaVersion = 2; });
     expect(gaps.status).toBe(0);
-    expect(JSON.parse(gaps.stdout ?? '')).toMatchObject({ overall: 'gaps' });
+    expect(JSON.parse(gaps.stdout ?? '')).toMatchObject({ overall: 'inconclusive' });
     expect(noReference.status).toBe(0);
-    expect(JSON.parse(noReference.stdout ?? '')).toMatchObject({ static: { reason: 'no_reference' } });
+    expect(JSON.parse(noReference.stdout ?? '')).toMatchObject({
+        static: { reason: 'no_reference' },
+        empirical: { classes: [expect.objectContaining({ outcome: 'coverage-unverifiable' })] },
+    });
     expect(malformed.status).toBe(1);
     expect(`${malformed.stdout ?? ''}${malformed.stderr ?? ''}`).toContain('schemaVersion must be 1');
 });

package/dist/tests/integration/sensor-structured-run.e2e.test.js

@@ -0,0 +1,127 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": 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 cliDir = path_1.default.resolve(__dirname, '../..');
+const bin = path_1.default.join(cliDir, 'dist/src/index.js');
+function writeJson(file, value) {
+    fs_1.default.mkdirSync(path_1.default.dirname(file), { recursive: true });
+    fs_1.default.writeFileSync(file, JSON.stringify(value, null, 2));
+}
+/**
+ * This is deliberately an argument which changes meaning under a shell on both
+ * POSIX and cmd.exe. The controlled Node tool records argv before the possible
+ * injected command can run, while the injected command would create the marker.
+ * A shell:true regression must therefore either alter argv or create the marker.
+ */
+const shellSensitiveLiteral = '--literal=preserve-this&node -e "require(\'fs\').writeFileSync(\'structured-shell-injection\', \'unexpected\')"';
+function createFixture() {
+    const root = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-structured-run-'));
+    const project = path_1.default.join(root, 'project');
+    const awmHome = path_1.default.join(root, 'awm-home');
+    const registryRoot = path_1.default.join(awmHome, 'registries', 'baseline');
+    const literal = shellSensitiveLiteral;
+    writeJson(path_1.default.join(project, 'package.json'), { name: 'structured-run-fixture', private: true });
+    // Local metadata is the compatibility evidence. It is not a tool found in a
+    // global installation, so init and run must keep resolving this fixture's pack.
+    writeJson(path_1.default.join(project, 'node_modules', 'fixture-sensor', 'package.json'), {
+        name: 'fixture-sensor', version: '1.0.0',
+    });
+    fs_1.default.writeFileSync(path_1.default.join(project, 'fixture-sensor.config.mjs'), 'export default {};\n');
+    fs_1.default.writeFileSync(path_1.default.join(project, 'fixture-sensor.mjs'), [
+        "import fs from 'fs';",
+        "fs.writeFileSync('structured-argv.json', JSON.stringify(process.argv.slice(2)));",
+    ].join('\n'));
+    writeJson(path_1.default.join(registryRoot, 'sensor-packs', 'fixture', 'pack.json'), {
+        schemaVersion: 2,
+        name: 'fixture',
+        description: 'compiled structured-run fixture',
+        detects: ['package.json'],
+        sensors: {
+            structured: {
+                applicability: { allFiles: ['package.json'] },
+                fast: true,
+                variants: [{
+                        id: 'fixture-v1', priority: 100,
+                        requirements: {
+                            tool: 'fixture-sensor', toolRange: '>=1 <2',
+                            runtime: 'node', runtimeRange: '>=20', configFiles: ['fixture-sensor.config.mjs'],
+                        },
+                        certifiedRange: '>=1 <2',
+                        // `node` is resolved from the process environment, but the actual
+                        // executable payload is the fixture-local script. Keeping the
+                        // literal as one argv element proves no shell parses it.
+                        command: { executable: 'node', resolution: 'path', args: ['fixture-sensor.mjs', literal] },
+                        assets: ['fixture-sensor.config.mjs'], formatter: 'generic', probe: { kind: 'config-present' },
+                    }],
+            },
+        },
+        coverage: {
+            schemaVersion: 1,
+            classes: {
+                'fixture-output': {
+                    description: 'fixture structured output', detectors: [{ sensor: 'structured' }],
+                    remedy: { summary: 'run the fixture sensor', command: 'awm sensors init --pack fixture' },
+                },
+            },
+        },
+    });
+    writeJson(path_1.default.join(awmHome, 'registries.json'), [{ name: 'baseline', remote: 'fixture' }]);
+    return { root, project, awmHome, registryRoot, literal };
+}
+function runCli(fixture, ...args) {
+    return (0, child_process_1.spawnSync)(process.execPath, [bin, 'sensors', ...args], {
+        cwd: fixture.project,
+        encoding: 'utf8',
+        env: { ...process.env, AWM_HOME: fixture.awmHome, AWM_NO_UPDATE_CHECK: '1' },
+    });
+}
+function assertSuccessfulCli(result, phase, requireStdout = false) {
+    const details = [
+        `status=${String(result.status)}`,
+        `signal=${String(result.signal)}`,
+        `error=${result.error ? `${result.error.name}: ${result.error.message}` : 'none'}`,
+        `stdout=${JSON.stringify(result.stdout ?? '')}`,
+        `stderr=${JSON.stringify(result.stderr ?? '')}`,
+    ].join('\n');
+    if (result.error || result.status !== 0 || result.signal !== null) {
+        throw new Error(`${phase} child process failed:\n${details}`);
+    }
+    if (requireStdout && !(result.stdout ?? '').trim()) {
+        throw new Error(`${phase} child process emitted no JSON:\n${details}`);
+    }
+}
+beforeAll(() => {
+    if (!fs_1.default.existsSync(bin))
+        throw new Error(`Structured sensor E2E requires the compiled CLI at ${bin}; run npm run build before this test.`);
+});
+test('compiled sensors run materializes a v2 registry command and passes its literal argv without a shell', () => {
+    const fixture = createFixture();
+    try {
+        const initialized = runCli(fixture, 'init', '--registry-root', fixture.registryRoot, '--pack', 'fixture', '--no-configure');
+        assertSuccessfulCli(initialized, 'init');
+        const manifest = JSON.parse(fs_1.default.readFileSync(path_1.default.join(fixture.project, '.awm', 'sensors.json'), 'utf8'));
+        expect(manifest).toMatchObject({
+            schemaVersion: 2,
+            pack: 'fixture',
+            sensors: { structured: { variantId: 'fixture-v1', command: { executable: 'node', resolution: 'path', args: ['fixture-sensor.mjs', fixture.literal] } } },
+        });
+        const result = runCli(fixture, 'run', '--fast');
+        assertSuccessfulCli(result, 'run --fast', true);
+        expect(JSON.parse(result.stdout)).toMatchObject({
+            overall: 'pass', sensors: [expect.objectContaining({ name: 'structured', status: 'pass' })],
+        });
+        expect(JSON.parse(fs_1.default.readFileSync(path_1.default.join(fixture.project, 'structured-argv.json'), 'utf8'))).toEqual([fixture.literal]);
+        // A shell:true mutation executes the trailing `& node -e ...` (or fails to
+        // preserve argv); this sentinel is the side-effect half of the regression.
+        expect(fs_1.default.existsSync(path_1.default.join(fixture.project, 'structured-shell-injection'))).toBe(false);
+    }
+    finally {
+        fs_1.default.rmSync(fixture.root, { recursive: true, force: true });
+    }
+});

package/dist/tests/structural/active-documentation.test.js

@@ -0,0 +1,128 @@
+"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 providers_1 = require("../../src/providers");
+const ROOT = path_1.default.resolve(__dirname, '../../..');
+const ACTIVE = [
+    'README.md',
+    'docs/README.md',
+    'docs/framework.md',
+    'docs/installation.md',
+    'docs/configuration.md',
+    'docs/project-setup.md',
+    'docs/agents-setup.md',
+    'docs/runbook.md',
+    'docs/cli-reference.md',
+    'docs/support-matrix.md',
+    'docs/architecture.md',
+    'docs/decisions.md',
+    'docs/guides/product-process.md',
+    'docs/guides/development-process.md',
+    'docs/guides/parallel-tracks.md',
+];
+const read = (file) => fs_1.default.readFileSync(path_1.default.join(ROOT, file), 'utf8');
+function slug(text) {
+    return text
+        .trim()
+        .toLowerCase()
+        .replace(/[`*_~]/g, '')
+        .replace(/[^\p{L}\p{N}\s-]/gu, '')
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-');
+}
+function anchors(markdown) {
+    const seen = new Map();
+    const out = new Set();
+    for (const match of markdown.matchAll(/^#{1,6}\s+(.+)$/gm)) {
+        const base = slug(match[1]);
+        const count = seen.get(base) ?? 0;
+        seen.set(base, count + 1);
+        out.add(count === 0 ? base : `${base}-${count}`);
+    }
+    for (const match of markdown.matchAll(/<a\s+(?:name|id)="([^"]+)"/g))
+        out.add(match[1]);
+    return out;
+}
+function localLinks(markdown) {
+    return Array.from(markdown.matchAll(/(?<!!)\[[^\]]+\]\(([^)]+)\)/g), (m) => m[1])
+        .filter((target) => !/^(?:https?:|mailto:)/.test(target));
+}
+describe('active documentation contract', () => {
+    it('has one reachable active editorial set (R1, R11, R14.4)', () => {
+        const navigation = read('README.md') + read('docs/README.md');
+        for (const file of ACTIVE) {
+            expect(fs_1.default.existsSync(path_1.default.join(ROOT, file))).toBe(true);
+            if (file !== 'README.md' && file !== 'docs/README.md') {
+                expect(navigation).toContain(file.replace(/^docs\//, ''));
+            }
+        }
+    });
+    it('keeps every relative link and anchor valid (R14.1)', () => {
+        for (const source of ACTIVE) {
+            for (const raw of localLinks(read(source))) {
+                const [filePart, fragment] = raw.split('#');
+                const target = filePart
+                    ? path_1.default.resolve(path_1.default.dirname(path_1.default.join(ROOT, source)), decodeURI(filePart))
+                    : path_1.default.join(ROOT, source);
+                expect(fs_1.default.existsSync(target)).toBe(true);
+                if (fragment && target.endsWith('.md')) {
+                    expect(anchors(fs_1.default.readFileSync(target, 'utf8'))).toContain(decodeURI(fragment));
+                }
+            }
+        }
+    });
+    it('documents the two-stage boundary and official bundle scopes (R3, R8)', () => {
+        expect(read('docs/installation.md')).toContain('Prepare the machine');
+        expect(read('docs/project-setup.md')).toContain('Initialize a project');
+        expect(read('docs/configuration.md')).toContain('`dev` and `product`');
+        expect(read('docs/project-setup.md')).toContain('`frontend`');
+    });
+    it('documents every init provider and option (R5, R14.2)', () => {
+        const config = read('docs/configuration.md');
+        for (const agent of providers_1.AGENT_TARGETS) {
+            expect(config).toContain(`awm init --agent ${agent} --machine-only`);
+        }
+        for (const flag of ['--agent', '--machine-only', '--yes', '--json']) {
+            expect(config).toContain(`\`${flag}\``);
+        }
+    });
+    it('assigns canonical topics instead of copying provider paths (R12)', () => {
+        expect(read('docs/configuration.md')).toContain('[Support matrix](support-matrix.md)');
+        expect(read('docs/configuration.md')).not.toMatch(/~\/\.(?:claude|codex|cursor|gemini)/);
+    });
+    it('keeps generated provider support prose in the canonical language (R2)', () => {
+        const matrix = read('docs/support-matrix.md');
+        expect(matrix).toContain('### Where each artifact is installed');
+        expect(matrix).toContain('### Agent profiles, workflows, hooks, and context');
+        expect(matrix).not.toContain('Dónde aterriza cada artefacto');
+        expect(matrix).not.toContain('Perfiles de agente, workflows, hooks y contexto');
+    });
+    it('keeps R3 canonical documentation in English and reachable from the hub', () => {
+        const hub = read('docs/README.md');
+        expect(hub).toContain('decisions.md');
+        for (const file of [
+            'docs/framework.md', 'docs/configuration.md', 'docs/project-setup.md',
+            'docs/runbook.md', 'docs/cli-reference.md', 'docs/support-matrix.md',
+            'docs/architecture.md',
+        ]) {
+            expect(read(file)).not.toContain('### Metodología');
+        }
+    });
+    it('keeps provider tiers, registries, and hook targets technically precise (R2)', () => {
+        const matrix = read('docs/support-matrix.md');
+        const runbook = read('docs/runbook.md');
+        const cliReference = read('docs/cli-reference.md');
+        expect(matrix).toContain('Re-anchors process guidance');
+        expect(matrix).toContain('Only `awm sensors run` is an enforceable deterministic gate');
+        expect(runbook).toContain('A registry needs at least one content directory');
+        expect(runbook).toMatch(/`catalog\.json` is required only when the registry\s+publishes bundles/);
+        expect(cliReference).toContain('`claude-code` and `codex`');
+        expect(cliReference).toContain('`--agent` is an alias for `--target`');
+        expect(cliReference).toContain('`dev` and `product` baseline bundles');
+        expect(runbook).toContain('bundles/<bundle-name>/bundle.json');
+    });
+});

package/dist/tests/structural/async-entrypoint.test.js

@@ -0,0 +1,15 @@
+"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 entrypoint = path_1.default.resolve(__dirname, '../../src/index.ts');
+describe('CLI async entrypoint contract', () => {
+    it('awaits Commander actions instead of starting them with parse()', () => {
+        const source = fs_1.default.readFileSync(entrypoint, 'utf8');
+        expect(source).toMatch(/program\.parseAsync\(\)\.catch\(/);
+        expect(source).not.toMatch(/\bprogram\.parse\(\);/);
+    });
+});

package/dist/tests/structural/jest-environment-is-isolated.test.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const os_1 = __importDefault(require("os"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 describe('Jest environment isolation', () => {
     it('does not inherit the operator Codex home', () => {
         expect(process.env.CODEX_HOME).toBeUndefined();
@@ -11,4 +13,46 @@ describe('Jest environment isolation', () => {
     it('uses a suite-owned temporary directory', () => {
         expect(os_1.default.tmpdir()).toContain('awm-jest-');
     });
+    it('falls back to the system temp directory when the home cache is read-only', async () => {
+        const originalEnv = { ...process.env };
+        const fallback = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-jest-fallback-'));
+        try {
+            jest.resetModules();
+            jest.doMock('os', () => ({
+                ...jest.requireActual('os'),
+                homedir: () => '/readonly-home',
+                tmpdir: () => fallback,
+            }));
+            const actualFs = jest.requireActual('fs');
+            jest.doMock('fs', () => ({
+                ...actualFs,
+                mkdirSync: jest.fn((target, ...args) => {
+                    if (String(target).includes('readonly-home')) {
+                        return undefined;
+                    }
+                    return actualFs.mkdirSync(target, ...args);
+                }),
+                mkdtempSync: jest.fn((prefix, ...args) => {
+                    if (prefix.includes('readonly-home')) {
+                        const error = new Error('read-only');
+                        error.code = 'EROFS';
+                        throw error;
+                    }
+                    return actualFs.mkdtempSync(prefix, ...args);
+                }),
+            }));
+            const setup = require('../../jest.global-setup.js');
+            await expect(setup()).resolves.toBeUndefined();
+            expect(process.env.AWM_JEST_TMPDIR?.startsWith(path_1.default.join(fallback, 'awm-cache', 'awm-jest-'))).toBe(true);
+        }
+        finally {
+            jest.dontMock('fs');
+            jest.dontMock('os');
+            jest.resetModules();
+            for (const key of Object.keys(process.env))
+                delete process.env[key];
+            Object.assign(process.env, originalEnv);
+            fs_1.default.rmSync(fallback, { recursive: true, force: true });
+        }
+    });
 });

package/dist/tests/structural/r3-cli-major-version.test.js

@@ -0,0 +1,37 @@
+"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 child_process_1 = require("child_process");
+const CLI_ROOT = path_1.default.resolve(__dirname, '../..');
+const DIST_ENTRYPOINT = path_1.default.join(CLI_ROOT, 'dist', 'src', 'index.js');
+const TARGET_VERSION = '7.0.0';
+function readJson(file) {
+    return JSON.parse(fs_1.default.readFileSync(path_1.default.join(CLI_ROOT, file), 'utf8'));
+}
+function runCompiledCli(...args) {
+    const result = (0, child_process_1.spawnSync)(process.execPath, [DIST_ENTRYPOINT, ...args], {
+        cwd: CLI_ROOT,
+        encoding: 'utf8',
+    });
+    expect(result.error).toBeUndefined();
+    expect(result.status).toBe(0);
+    return `${result.stdout}${result.stderr}`;
+}
+describe('R3 public major CLI release contract', () => {
+    it('declares 7.0.0 consistently in package metadata and the lockfile root', () => {
+        const pkg = readJson('package.json');
+        const lock = readJson('package-lock.json');
+        const root = lock.packages[''];
+        expect(pkg.version).toBe(TARGET_VERSION);
+        expect(lock.version).toBe(TARGET_VERSION);
+        expect(root.version).toBe(TARGET_VERSION);
+    });
+    it('exposes 7.0.0 from the compiled CLI while retaining its help banner', () => {
+        expect(runCompiledCli('--version').trim()).toBe(TARGET_VERSION);
+        expect(runCompiledCli('--help')).toContain('Usage: awm');
+    });
+});

package/dist/tests/structural/sensor-documentation-contract.test.js

@@ -0,0 +1,77 @@
+"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 commander_1 = require("commander");
+jest.mock('@clack/prompts', () => ({
+    log: { error: jest.fn(), success: jest.fn(), warn: jest.fn(), info: jest.fn() },
+}));
+const manifest_1 = require("../../src/commands/sensors/compatibility/manifest");
+const ledger_1 = require("../../src/commands/ledger");
+const sensors_1 = require("../../src/commands/sensors");
+const ROOT = path_1.default.resolve(__dirname, '../../..');
+const read = (file) => fs_1.default.readFileSync(path_1.default.join(ROOT, file), 'utf8');
+function documentedJson(files) {
+    return files.flatMap((file) => Array.from(read(file).matchAll(/```json\s*\n([\s\S]*?)```/g), (match) => JSON.parse(match[1])));
+}
+function helpFor(command) {
+    const program = new commander_1.Command().name('awm');
+    (0, sensors_1.registerSensorsCommand)(program);
+    (0, ledger_1.registerLedgerCommand)(program);
+    const [parent, child] = command.split(' ');
+    return program.commands.find((entry) => entry.name() === parent)
+        .commands.find((entry) => entry.name() === child).helpInformation();
+}
+describe('R3 canonical sensor documentation', () => {
+    test.each([
+        ['docs/framework.md', ['Static coverage', 'Empirical coverage', 'retrospective feedback loop']],
+        ['docs/configuration.md', ['pack schema v2', 'legacy pack', 'compatible-unverified']],
+        ['docs/project-setup.md', ['version-aware', 'hardening opt-in']],
+        ['docs/runbook.md', ['awm sensors coverage --min', 'compatibility drift', 'orphaned asset']],
+        ['docs/cli-reference.md', ['schemaVersion: 2', '--defect-class', '--min']],
+        ['docs/architecture.md', ['compatibility resolver', 'bounded probe']],
+    ])('%s owns its R3 subject', (file, phrases) => {
+        const text = read(file);
+        phrases.forEach((phrase) => expect(text).toContain(phrase));
+    });
+    test('parses every documented v2 sensor manifest example with the production parser', () => {
+        const examples = documentedJson(['docs/configuration.md', 'docs/cli-reference.md'])
+            .filter((value) => typeof value === 'object' && value !== null && value.schemaVersion === 2);
+        expect(examples.length).toBeGreaterThan(0);
+        examples.forEach((example) => expect(() => (0, manifest_1.parseSensorManifest)(example, 'documented example')).not.toThrow());
+    });
+    test('keeps documented v2 sensor manifests portable across native platforms', () => {
+        const examples = documentedJson(['docs/configuration.md', 'docs/cli-reference.md'])
+            .filter((value) => typeof value === 'object' && value !== null && value.schemaVersion === 2);
+        expect(examples.length).toBeGreaterThan(0);
+        examples.forEach((example) => expect(example).not.toHaveProperty('registryRoot'));
+    });
+    test('documents exact Commander flags', () => {
+        expect(helpFor('sensors coverage')).toContain('--min <count>');
+        expect(helpFor('ledger add')).toContain('--defect-class <id>');
+        const reference = read('docs/cli-reference.md');
+        expect(reference).toContain('awm sensors coverage [--json] [--min <count>]');
+        expect(reference).toContain('--defect-class <id>');
+    });
+    test('does not overstate the human coverage renderer or retrospective archive wiring', () => {
+        const reference = read('docs/cli-reference.md');
+        const runbook = read('docs/runbook.md');
+        expect(reference).toMatch(/safe,\s+sanitized evidence references and safe cluster signatures/);
+        expect(reference).toMatch(/never ledger\s+descriptions, raw ledger lines, or unsafe values/);
+        expect(runbook).toContain('Run `awm sensors coverage --min 2` manually before archive');
+        expect(runbook).toMatch(/Automatic\s+coverage-before-archive enforcement is delivered by the registry in T12/);
+        expect(runbook).not.toContain('it automatically evaluates\ncoverage feedback');
+    });
+    test('keeps archival coverage manual until registry enforcement and scopes v2 binary resolution', () => {
+        const framework = read('docs/framework.md');
+        const osMatrix = read('docs/testing/os-matrix.md');
+        expect(framework).toMatch(/manual operator step[\s\S]*until the registry delivers automatic enforcement in T12/i);
+        expect(osMatrix).toMatch(/v2 local resolution modes use project-local `node_modules` or `.venv`\/`venv`\s+environments/i);
+        expect(osMatrix).toMatch(/Windows `.cmd`\/`.bat` wrappers are rejected for structured v2\s+commands/i);
+        expect(osMatrix).toMatch(/Legacy string\s+commands remain separate and retain their documented shell\/PATH semantics/i);
+        expect(osMatrix).not.toContain('Sensors resolve their binaries on PATH');
+    });
+});

package/dist/tests/structural/support-matrix-is-current.test.js

@@ -16,7 +16,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // Este test hace que ese desvio sea imposible de mergear. No verifica que la tabla sea
 // "linda": verifica que sea LA MISMA que produce el codigo hoy.
 const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 const support_matrix_1 = require("../../scripts/support-matrix");
+const sensor_support_matrix_1 = require("../../scripts/sensor-support-matrix");
+const SENSOR_FIXTURE_REGISTRY = path_1.default.join(__dirname, '..', 'fixtures', 'sensor-support-matrix', 'registry');
 describe('docs/support-matrix.md refleja el codigo', () => {
     it('el bloque generado esta al dia', () => {
         const doc = fs_1.default.readFileSync(support_matrix_1.DOC_PATH, 'utf-8');
@@ -30,6 +33,18 @@ describe('docs/support-matrix.md refleja el codigo', () => {
         expect(doc).toContain(support_matrix_1.BEGIN_MARKER);
         expect(doc).toContain(support_matrix_1.END_MARKER);
     });
+    it('the generated pre-publication v2 sensor-pack contract fixture is current', () => {
+        const doc = fs_1.default.readFileSync(support_matrix_1.DOC_PATH, 'utf-8');
+        expect(doc).toContain(sensor_support_matrix_1.SENSOR_BEGIN_MARKER);
+        expect(doc).toContain(sensor_support_matrix_1.SENSOR_END_MARKER);
+        expect(doc).toContain(sensor_support_matrix_1.R3_PREPUBLICATION_FIXTURE_PURPOSE);
+        expect(doc).toContain('not the published `awm-baseline-registry` manifests');
+        expect(doc).toBe((0, sensor_support_matrix_1.spliceSensorSupportMatrix)(doc, (0, sensor_support_matrix_1.renderSensorSupportMatrix)(SENSOR_FIXTURE_REGISTRY)));
+    });
+    it('pins the documentation generator to the declared R3 pre-publication fixture', () => {
+        const packageJson = JSON.parse(fs_1.default.readFileSync(path_1.default.join(__dirname, '..', '..', 'package.json'), 'utf8'));
+        expect(packageJson.scripts?.['docs:matrix']).toContain(`--registry-root ${sensor_support_matrix_1.R3_PREPUBLICATION_FIXTURE_RELATIVE_PATH}`);
+    });
     it('la tabla nombra a los seis providers declarados', () => {
         // Que el bloque este "al dia" no sirve si el generador se olvidara de un provider:
         // doc y generador coincidirian, los dos incompletos.
@@ -61,6 +76,58 @@ describe('docs/support-matrix.md refleja el codigo', () => {
             jest.resetModules();
         }
     });
+    it('documents default provider paths even when this machine overrides CODEX_HOME', () => {
+        const saved = process.env.CODEX_HOME;
+        process.env.CODEX_HOME = '/private/codex-home';
+        try {
+            jest.resetModules();
+            const { renderProviderTables: fresh } = require('../../scripts/support-matrix');
+            expect(fresh()).toContain('`~/.codex/agents`');
+            expect(fresh()).not.toContain('/private/codex-home');
+        }
+        finally {
+            if (saved === undefined)
+                delete process.env.CODEX_HOME;
+            else
+                process.env.CODEX_HOME = saved;
+            jest.resetModules();
+        }
+    });
+    it('does not leak a normalized CODEX_HOME override into generated documentation', () => {
+        const saved = process.env.CODEX_HOME;
+        process.env.CODEX_HOME = '/private/codex/../secret-codex/';
+        try {
+            jest.resetModules();
+            const { renderProviderTables: fresh } = require('../../scripts/support-matrix');
+            const generated = fresh();
+            expect(generated).toContain('`~/.codex/agents`');
+            expect(generated).not.toContain('/private/');
+            expect(generated).not.toContain('secret-codex');
+        }
+        finally {
+            if (saved === undefined)
+                delete process.env.CODEX_HOME;
+            else
+                process.env.CODEX_HOME = saved;
+            jest.resetModules();
+        }
+    });
+    it('keeps a separator when CODEX_HOME has a trailing slash', () => {
+        const saved = process.env.CODEX_HOME;
+        process.env.CODEX_HOME = '/private/codex-home/';
+        try {
+            jest.resetModules();
+            const { renderProviderTables: fresh } = require('../../scripts/support-matrix');
+            expect(fresh()).toContain('`~/.codex/agents`');
+        }
+        finally {
+            if (saved === undefined)
+                delete process.env.CODEX_HOME;
+            else
+                process.env.CODEX_HOME = saved;
+            jest.resetModules();
+        }
+    });
     // La abreviacion a `~` se probaba solo end-to-end, y en Linux eso no distingue entre
     // "normaliza bien" y "los separadores ya coincidian". La CI de Windows encontro que no
     // normalizaba: comparaba el prefijo ANTES de convertir separadores, asi que alla no
@@ -89,12 +156,12 @@ describe('docs/support-matrix.md refleja el codigo', () => {
         expect(out).toContain('linea uno\r\nlinea dos');
         expect(out.split('\r\n').length - 1).toBe(out.split('\n').length - 1); // ni un LF suelto
     });
-    it('marca como no soportado, no como ausente, el scope que un provider no tiene', () => {
+    it('marks an unsupported scope rather than leaving it absent', () => {
         // La diferencia entre "no soportado" y una celda vacia es exactamente lo que el
         // documento existe para no dejar ambiguo: Copilot no tiene scope global por
         // decision del producto que integramos, no porque falte implementarlo.
         const generated = (0, support_matrix_1.renderProviderTables)();
         const copilotRow = generated.split('\n').find((l) => l.startsWith('| `copilot` |'));
-        expect(copilotRow).toContain('**no soportado**');
+        expect(copilotRow).toContain('**unsupported**');
     });
 });