agentic-workflow-manager 9.17.0 → 9.19.0

package/dist/src/core/facts/needs.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSkillNeeds = readSkillNeeds;
+exports.findOrphanNeeds = findOrphanNeeds;
+const fs_1 = __importDefault(require("fs"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const frontmatter_1 = require("../frontmatter");
+const types_1 = require("./types");
+/**
+ * Read the `needs` list from a skill SKILL.md frontmatter.
+ * Absent → `[]`. Invalid shape → {@link SkillNeedsError}.
+ */
+function readSkillNeeds(skillMdPath) {
+    let raw;
+    try {
+        const stat = fs_1.default.lstatSync(skillMdPath);
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            throw new types_1.SkillNeedsError(`Skill path ${skillMdPath} must be a regular file`);
+        }
+        raw = fs_1.default.readFileSync(skillMdPath, 'utf-8');
+    }
+    catch (e) {
+        if (e instanceof types_1.SkillNeedsError)
+            throw e;
+        throw new types_1.SkillNeedsError(`Cannot read skill at ${skillMdPath}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const block = (0, frontmatter_1.matchFrontmatterBlock)(raw);
+    if (block === null)
+        return [];
+    let parsed;
+    try {
+        parsed = js_yaml_1.default.load(block);
+    }
+    catch (e) {
+        throw new types_1.SkillNeedsError(`Invalid skill frontmatter at ${skillMdPath}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (parsed === null || parsed === undefined)
+        return [];
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new types_1.SkillNeedsError(`Invalid skill frontmatter at ${skillMdPath}: expected a mapping`);
+    }
+    const needs = parsed.needs;
+    if (needs === undefined)
+        return [];
+    if (!Array.isArray(needs) || needs.some((n) => typeof n !== 'string' || n === '')) {
+        throw new types_1.SkillNeedsError(`Invalid needs at ${skillMdPath}: needs must be a YAML list of non-empty strings`);
+    }
+    return needs;
+}
+/** Ids in `needs` that are absent from the catalog (fail-closed; never invent). */
+function findOrphanNeeds(needs, catalog) {
+    // Own keys only — `in` would treat Object.prototype (toString, …) as catalog facts.
+    return needs.filter((id) => !Object.hasOwn(catalog.facts, id));
+}

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

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillNeedsError = exports.FactsCatalogError = exports.FACT_ID_RE = exports.FACTS_MIN_CLI_VERSION = void 0;
+/** First CLI version that understands registry facts / needs. Bump only with intentional release. */
+exports.FACTS_MIN_CLI_VERSION = '9.18.0';
+/** Dotted fact ids: `repos.root`, `aws.profile.dev`. */
+exports.FACT_ID_RE = /^[a-z][a-z0-9]*(\.[a-z0-9]+)+$/;
+class FactsCatalogError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FactsCatalogError';
+    }
+}
+exports.FactsCatalogError = FactsCatalogError;
+class SkillNeedsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SkillNeedsError';
+    }
+}
+exports.SkillNeedsError = SkillNeedsError;

package/dist/src/index.js

@@ -37,6 +37,7 @@ const doctor_1 = require("./commands/doctor");
 const backup_1 = require("./commands/backup");
 const init_1 = require("./commands/init");
 const registry_1 = require("./commands/registry");
+const env_1 = require("./commands/env");
 const pin_1 = require("./commands/pin");
 const export_1 = require("./commands/export");
 const agent_1 = require("./commands/agent");
@@ -743,6 +744,7 @@ miroCmd.command('sync <storyMapPath>')
 (0, backup_1.registerBackupCommand)(exports.program);
 (0, init_1.registerInitCommand)(exports.program);
 (0, registry_1.registerRegistryCommand)(exports.program);
+(0, env_1.registerEnvCommand)(exports.program);
 (0, pin_1.registerPinCommands)(exports.program);
 (0, export_1.registerExportCommand)(exports.program);
 (0, agent_1.registerAgentCommand)(exports.program);

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

@@ -0,0 +1,261 @@
+"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 os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const commander_1 = require("commander");
+const env_1 = require("../../../src/commands/env");
+const store_1 = require("../../../src/core/environments/store");
+const catalog = {
+    schemaVersion: 1,
+    facts: {
+        'repos.root': {
+            valueType: 'path',
+            resolution: 'prompt',
+            durability: 'durable',
+            inject: 'reference',
+        },
+        'aws.profile': {
+            valueType: 'string',
+            resolution: 'prompt',
+            durability: 'durable',
+            inject: 'reference',
+        },
+        'env.kind': {
+            valueType: 'enum',
+            resolution: 'prompt',
+            durability: 'durable',
+            inject: 'reference',
+            values: ['dev', 'prod'],
+        },
+        'aws.token': {
+            valueType: 'string',
+            resolution: 'prompt',
+            durability: 'volatile',
+            inject: 'reference',
+            ttl: 1,
+        },
+    },
+};
+function isolateHome() {
+    const tmp = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-env-cmd-'));
+    process.env.AWM_HOME = path_1.default.join(tmp, '.awm');
+    process.env.HOME = tmp;
+    return tmp;
+}
+async function run(argv, loadCatalog = () => catalog, extraDeps = {}) {
+    const prog = new commander_1.Command();
+    prog.exitOverride();
+    prog.configureOutput({ writeErr: () => undefined });
+    (0, env_1.registerEnvCommand)(prog, {
+        loadCatalog,
+        consultedRoots: () => ['/tmp/test-registry'],
+        stdinIsTTY: () => false,
+        ...extraDeps,
+    });
+    const outSpy = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    const errSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const logSpy = jest.spyOn(console, 'log').mockImplementation(() => undefined);
+    const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+    try {
+        await prog.parseAsync(['node', 'awm', 'env', ...argv]);
+    }
+    finally {
+        // keep spies until we collect
+    }
+    const out = outSpy.mock.calls.map((c) => String(c[0])).join('') +
+        logSpy.mock.calls.map((c) => c.map(String).join(' ')).join('\n');
+    const err = errSpy.mock.calls.map((c) => String(c[0])).join('') +
+        errorSpy.mock.calls.map((c) => c.map(String).join(' ')).join('\n');
+    outSpy.mockRestore();
+    errSpy.mockRestore();
+    logSpy.mockRestore();
+    errorSpy.mockRestore();
+    return { out, err };
+}
+describe('awm env commands (RF-2, RF-3.3)', () => {
+    let tmp;
+    let prevHome;
+    let prevAwm;
+    beforeEach(() => {
+        prevHome = process.env.HOME;
+        prevAwm = process.env.AWM_HOME;
+        tmp = isolateHome();
+    });
+    afterEach(() => {
+        fs_1.default.rmSync(tmp, { recursive: true, force: true });
+        if (prevHome === undefined)
+            delete process.env.HOME;
+        else
+            process.env.HOME = prevHome;
+        if (prevAwm === undefined)
+            delete process.env.AWM_HOME;
+        else
+            process.env.AWM_HOME = prevAwm;
+    });
+    it('set --value writes under environments/default/values.json without shelling out (RF-2.1, RF-3.3)', async () => {
+        const spawn = jest.spyOn(require('child_process'), 'spawnSync');
+        const execFile = jest.spyOn(require('child_process'), 'execFileSync');
+        await run(['set', 'repos.root', '--value', '/machine/repos']);
+        expect((0, store_1.readValues)('default')['repos.root'].value).toBe('/machine/repos');
+        expect(fs_1.default.existsSync((0, store_1.valuesPath)('default'))).toBe(true);
+        expect((0, store_1.valuesPath)('default')).toContain(path_1.default.join('.awm', 'environments', 'default', 'values.json'));
+        expect(spawn).not.toHaveBeenCalled();
+        expect(execFile).not.toHaveBeenCalled();
+        spawn.mockRestore();
+        execFile.mockRestore();
+    });
+    it('status reports missing for unset facts and fresh after set (RF-2.5)', async () => {
+        let { out } = await run(['status']);
+        expect(out).toMatch(/repos\.root:\s*missing/);
+        expect(out).toMatch(/aws\.profile:\s*missing/);
+        await run(['set', 'repos.root', '--value', '/r']);
+        ({ out } = await run(['status']));
+        expect(out).toMatch(/repos\.root:\s*fresh/);
+        // Unset sibling stays missing — no silent default invent for other ids.
+        expect(out).toMatch(/aws\.profile:\s*missing/);
+        expect(out).not.toMatch(/aws\.profile:\s*fresh/);
+    });
+    it('status reports stale for expired volatile fact (RF-2.5)', async () => {
+        (0, store_1.writeFact)('default', 'aws.token', {
+            value: 'tok',
+            status: 'fresh',
+            updatedAt: '2026-10-12T00:00:00.000Z',
+        }, { definition: catalog.facts['aws.token'] });
+        const { out } = await run(['status'], () => catalog, {
+            now: () => new Date('2026-10-12T00:00:02.000Z'),
+        });
+        expect(out).toMatch(/aws\.token:\s*stale/);
+    });
+    it('edit prints absolute store path', async () => {
+        const { out } = await run(['edit']);
+        expect(out).toContain((0, store_1.valuesPath)((0, store_1.getActiveEnvironmentName)()));
+        expect(path_1.default.isAbsolute(out.trim().split(/\s+/).find((t) => t.includes('values.json')) || (0, store_1.valuesPath)('default'))).toBe(true);
+    });
+    it('refresh --value updates an existing fact without shell (RF-3.3)', async () => {
+        await run(['set', 'aws.profile', '--value', 'old']);
+        await run(['refresh', 'aws.profile', '--value', 'new-profile']);
+        expect((0, store_1.readValues)('default')['aws.profile'].value).toBe('new-profile');
+    });
+    it('refresh without --value in non-interactive mode errors', async () => {
+        await run(['set', 'aws.profile', '--value', 'old']);
+        await expect(run(['refresh', 'aws.profile'])).rejects.toThrow(/--value|value/i);
+    });
+    it('use switches active environment (RF-2.2)', async () => {
+        await run(['use', 'staging']);
+        expect((0, store_1.getActiveEnvironmentName)()).toBe('staging');
+        await run(['set', 'repos.root', '--value', '/staging/repos']);
+        expect((0, store_1.valuesPath)('staging')).toContain(`${path_1.default.sep}staging${path_1.default.sep}values.json`);
+        expect((0, store_1.readValues)('staging')['repos.root'].value).toBe('/staging/repos');
+    });
+    it('set unknown id errors listing consulted roots', async () => {
+        await expect(run(['set', 'no.such.fact', '--value', 'x'])).rejects.toThrow(/no\.such\.fact/);
+        await expect(run(['set', 'no.such.fact', '--value', 'x'])).rejects.toThrow(/test-registry/);
+        expect((0, store_1.readValues)('default')).toEqual({});
+    });
+    it('set rejects empty path and leaves store unchanged', async () => {
+        await expect(run(['set', 'repos.root', '--value', ''])).rejects.toThrow(/path|empty|value/i);
+        expect((0, store_1.readValues)('default')).toEqual({});
+    });
+    it('set rejects invalid enum value', async () => {
+        await expect(run(['set', 'env.kind', '--value', 'qa'])).rejects.toThrow(/enum|dev|prod/i);
+        expect((0, store_1.readValues)('default')).toEqual({});
+    });
+    it('set never imports child_process for resolution (RF-3.3)', () => {
+        const src = fs_1.default.readFileSync(path_1.default.join(__dirname, '../../../src/commands/env/index.ts'), 'utf-8');
+        expect(src).not.toMatch(/child_process/);
+        expect(src).not.toMatch(/\bexecSync\b|\bspawnSync\b|\bexecFileSync\b/);
+    });
+    it('set without --value on TTY uses promptFn (RF-3.3)', async () => {
+        const prompts = [];
+        await run(['set', 'repos.root'], () => catalog, {
+            stdinIsTTY: () => true,
+            promptValue: (q) => {
+                prompts.push(q);
+                return '/prompted/repos';
+            },
+        });
+        expect(prompts.length).toBeGreaterThanOrEqual(1);
+        expect((0, store_1.readValues)('default')['repos.root'].value).toBe('/prompted/repos');
+    });
+    it('set without --value when not TTY keeps requireValue error (RF-3.3)', async () => {
+        await expect(run(['set', 'repos.root'], () => catalog, { stdinIsTTY: () => false })).rejects.toThrow(/--value|value/i);
+    });
+    it('refresh --all on TTY prompts each store id via promptFn', async () => {
+        await run(['set', 'repos.root', '--value', '/old']);
+        await run(['set', 'aws.profile', '--value', 'old-profile']);
+        const seen = [];
+        const answers = {
+            'repos.root': '/new',
+            'aws.profile': 'new-profile',
+        };
+        await run(['refresh', '--all'], () => catalog, {
+            stdinIsTTY: () => true,
+            promptValue: (q) => {
+                const id = Object.keys(answers).find((k) => q.includes(k));
+                if (!id)
+                    throw new Error(`unexpected prompt: ${q}`);
+                seen.push(id);
+                return answers[id];
+            },
+        });
+        expect(seen.sort()).toEqual(['aws.profile', 'repos.root']);
+        expect((0, store_1.readValues)('default')['repos.root'].value).toBe('/new');
+        expect((0, store_1.readValues)('default')['aws.profile'].value).toBe('new-profile');
+    });
+    it('refresh --all when not TTY keeps clear error', async () => {
+        await run(['set', 'repos.root', '--value', '/old']);
+        await expect(run(['refresh', '--all'], () => catalog, { stdinIsTTY: () => false })).rejects.toThrow(/--all|interactive|factId|--value|TTY/i);
+    });
+    it('inject prints buildInjection JSON (default reference)', async () => {
+        await run(['set', 'repos.root', '--value', '/r']);
+        const { out } = await run(['inject']);
+        const parsed = JSON.parse(out.trim());
+        expect(parsed.mode).toBe('reference');
+        expect(parsed.storePath).toContain('values.json');
+        expect(parsed.factIds).toEqual(expect.arrayContaining(['repos.root']));
+        expect(parsed.values).toBeUndefined();
+    });
+    it('inject --mode context includes fresh context values when catalog allows', async () => {
+        const contextCatalog = {
+            schemaVersion: 1,
+            facts: {
+                'team.color': {
+                    valueType: 'string',
+                    resolution: 'prompt',
+                    durability: 'durable',
+                    inject: 'context',
+                },
+            },
+        };
+        await run(['set', 'team.color', '--value', 'blue'], () => contextCatalog);
+        const { out } = await run(['inject', '--mode', 'context'], () => contextCatalog);
+        const parsed = JSON.parse(out.trim());
+        expect(parsed.mode).toBe('context');
+        expect(parsed.values).toEqual({ 'team.color': 'blue' });
+    });
+    it('mergeFactDefinitions refuses to weaken volatile → durable (secret revive)', () => {
+        const into = {
+            'aws.token': {
+                valueType: 'string',
+                resolution: 'prompt',
+                durability: 'volatile',
+                inject: 'context',
+                ttl: 60,
+            },
+        };
+        (0, env_1.mergeFactDefinitions)(into, {
+            'aws.token': {
+                valueType: 'string',
+                resolution: 'prompt',
+                durability: 'durable',
+                inject: 'context',
+            },
+        });
+        expect(into['aws.token'].durability).toBe('volatile');
+        expect(into['aws.token'].ttl).toBe(60);
+    });
+});

package/dist/tests/commands/registry/doctor.test.js

@@ -0,0 +1,283 @@
+"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 os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const types_1 = require("../../../src/core/facts/types");
+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) + '\n');
+}
+function handbook(rows) {
+    const body = rows.length === 0 ? '' : rows.map((r) => `| ${r} |`).join('\n') + '\n';
+    return `# fixture
+
+## Capabilities
+| id | status | notes |
+|----|--------|-------|
+${body}
+## Capability: facts
+Facts chapter.
+`;
+}
+/** Minimal registry that passes structural doctor when facts are unused. */
+function scaffoldBare(root, opts) {
+    fs_1.default.mkdirSync(path_1.default.join(root, 'skills'), { recursive: true });
+    writeJson(path_1.default.join(root, 'awm-registry.json'), {
+        overrides: [],
+        ...(opts?.minCliVersion !== undefined ? { minCliVersion: opts.minCliVersion } : {}),
+    });
+    const catalogVersion = opts?.catalogVersion ?? '1.0.0';
+    if (opts?.withBundle !== false) {
+        writeJson(path_1.default.join(root, 'catalog.json'), {
+            version: 1,
+            bundles: [{ name: 'demo', source: 'bundles/demo', version: catalogVersion, scope: 'project' }],
+        });
+        writeJson(path_1.default.join(root, 'bundles', 'demo', 'bundle.json'), {
+            name: 'demo',
+            version: opts?.bundleVersion ?? catalogVersion,
+            skills: [],
+        });
+    }
+    else {
+        writeJson(path_1.default.join(root, 'catalog.json'), { version: 1, bundles: [] });
+    }
+    fs_1.default.writeFileSync(path_1.default.join(root, 'REGISTRY.md'), opts?.handbook ?? handbook(['facts | active | see chapter']));
+    if (opts?.facts !== undefined) {
+        writeJson(path_1.default.join(root, 'facts.json'), opts.facts);
+    }
+}
+describe('doctorRegistry (RF-4.4–4.8, RF-5.1)', () => {
+    let tmp;
+    beforeEach(() => {
+        tmp = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-doctor-'));
+        jest.resetModules();
+    });
+    afterEach(() => {
+        fs_1.default.rmSync(tmp, { recursive: true, force: true });
+    });
+    function loadDoctor() {
+        return require('../../../src/commands/registry/doctor');
+    }
+    it('reports missing REGISTRY.md as structural', () => {
+        const root = path_1.default.join(tmp, 'no-handbook');
+        scaffoldBare(root, { withBundle: false, minCliVersion: types_1.FACTS_MIN_CLI_VERSION });
+        fs_1.default.unlinkSync(path_1.default.join(root, 'REGISTRY.md'));
+        const { doctorRegistry } = loadDoctor();
+        const report = doctorRegistry(root);
+        expect(report.structural.some((m) => /missing REGISTRY\.md/i.test(m))).toBe(true);
+    });
+    it('reports missing Capabilities index as structural', () => {
+        const root = path_1.default.join(tmp, 'no-caps');
+        scaffoldBare(root, {
+            withBundle: false,
+            minCliVersion: types_1.FACTS_MIN_CLI_VERSION,
+            handbook: '# fixture\n\nNo capabilities table here.\n',
+        });
+        const { doctorRegistry } = loadDoctor();
+        const report = doctorRegistry(root);
+        expect(report.structural.some((m) => /Capabilities/i.test(m))).toBe(true);
+    });
+    it('reports catalog vs bundle.json version skew as structural (RF-4.7)', () => {
+        const root = path_1.default.join(tmp, 'skew');
+        scaffoldBare(root, {
+            minCliVersion: types_1.FACTS_MIN_CLI_VERSION,
+            catalogVersion: '1.0.0',
+            bundleVersion: '2.0.0',
+        });
+        const { doctorRegistry } = loadDoctor();
+        const report = doctorRegistry(root);
+        expect(report.structural.some((m) => /version/i.test(m) && /demo/i.test(m))).toBe(true);
+    });
+    it('reports environment store files under registry tree as structural (RF-4.5)', () => {
+        const root = path_1.default.join(tmp, 'store-in-tree');
+        scaffoldBare(root, { withBundle: false, minCliVersion: types_1.FACTS_MIN_CLI_VERSION });
+        const store = path_1.default.join(root, 'environments', 'default', 'values.json');
+        writeJson(store, { 'repos.root': { value: '/x', status: 'fresh', updatedAt: '2026-01-01T00:00:00Z' } });
+        const { doctorRegistry } = loadDoctor();
+        const report = doctorRegistry(root);
+        expect(report.structural.some((m) => /environments/i.test(m) || /values\.json/i.test(m))).toBe(true);
+    });
+    it('reports environments symlink into external store as structural (RF-4.5)', () => {
+        const root = path_1.default.join(tmp, 'store-symlink');
+        scaffoldBare(root, { withBundle: false, minCliVersion: types_1.FACTS_MIN_CLI_VERSION });
+        const external = path_1.default.join(tmp, 'external-env');
+        writeJson(path_1.default.join(external, 'default', 'values.json'), {
+            'repos.root': { value: '/x', status: 'fresh', updatedAt: '2026-01-01T00:00:00Z' },
+        });
+        fs_1.default.symlinkSync(external, path_1.default.join(root, 'environments'));
+        const { doctorRegistry } = loadDoctor();
+        const report = doctorRegistry(root);
+        expect(report.structural.some((m) => /environments/i.test(m) && /symlink|RF-4\.5/i.test(m))).toBe(true);
+    });
+    it('reports values.json / meta.json symlinks under environments as structural (RF-4.5)', () => {
+        const root = path_1.default.join(tmp, 'store-file-symlink');
+        scaffoldBare(root, { withBundle: false, minCliVersion: types_1.FACTS_MIN_CLI_VERSION });
+        const external = path_1.default.join(tmp, 'external-values.json');
+        fs_1.default.writeFileSync(external, '{"x":1}\n');
+        fs_1.default.mkdirSync(path_1.default.join(root, 'environments', 'default'), { recursive: true });
+        fs_1.default.symlinkSync(external, path_1.default.join(root, 'environments', 'default', 'values.json'));
+        const { doctorRegistry } = loadDoctor();
+        const report = doctorRegistry(root);
+        expect(report.structural.some((m) => /values\.json/i.test(m))).toBe(true);
+    });
+    it('treats unknown capability id widgets as advisory only; doctorExitCode is 0 (RF-4.4/4.6)', () => {
+        const root = path_1.default.join(tmp, 'widgets');
+        scaffoldBare(root, {
+            withBundle: false,
+            minCliVersion: types_1.FACTS_MIN_CLI_VERSION,
+            handbook: handbook(['widgets | planned | future']),
+        });
+        const { doctorRegistry, doctorExitCode } = loadDoctor();
+        const report = doctorRegistry(root);
+        expect(report.structural).toEqual([]);
+        expect(report.advisories.some((m) => /widgets/i.test(m))).toBe(true);
+        expect(doctorExitCode(report)).toBe(0);
+        expect(doctorExitCode({ structural: ['x'], advisories: [] })).toBe(1);
+    });
+    it('fails structurally when facts present and minCliVersion below FACTS_MIN_CLI_VERSION (RF-4.8)', () => {
+        const root = path_1.default.join(tmp, 'old-cli');
+        scaffoldBare(root, {
+            withBundle: false,
+            minCliVersion: '9.17.0',
+            facts: { schemaVersion: 1, facts: {} },
+        });
+        const { doctorRegistry } = loadDoctor();
+        const report = doctorRegistry(root);
+        expect(report.structural.some((m) => /minCliVersion/i.test(m) || /9\.18\.0/.test(m))).toBe(true);
+    });
+    it('advises on prose home-path hints like ~/Developments', () => {
+        const root = path_1.default.join(tmp, 'prose');
+        scaffoldBare(root, { withBundle: false, minCliVersion: types_1.FACTS_MIN_CLI_VERSION });
+        const skillDir = path_1.default.join(root, 'skills', 'demo');
+        fs_1.default.mkdirSync(skillDir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(skillDir, 'SKILL.md'), `---\nname: demo\ndescription: d\n---\nClone under ~/Developments/team.\n`);
+        const { doctorRegistry } = loadDoctor();
+        const report = doctorRegistry(root);
+        expect(report.advisories.some((m) => /~\/Developments|home path|machine path/i.test(m))).toBe(true);
+    });
+    it('reports orphan needs as structural when facts.json exists (RF-1.3)', () => {
+        const root = path_1.default.join(tmp, 'orphan');
+        scaffoldBare(root, {
+            withBundle: false,
+            minCliVersion: types_1.FACTS_MIN_CLI_VERSION,
+            facts: {
+                schemaVersion: 1,
+                facts: { 'repos.root': { valueType: 'path' } },
+            },
+        });
+        const skillDir = path_1.default.join(root, 'skills', 'demo');
+        fs_1.default.mkdirSync(skillDir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(skillDir, 'SKILL.md'), `---\nname: demo\ndescription: d\nneeds:\n  - ghost.fact\n---\n# Demo\n`);
+        const { doctorRegistry } = loadDoctor();
+        const report = doctorRegistry(root);
+        expect(report.structural.some((m) => /ghost\.fact|orphan/i.test(m))).toBe(true);
+    });
+    it('reports needs without facts.json as structural (fail closed)', () => {
+        const root = path_1.default.join(tmp, 'needs-no-catalog');
+        scaffoldBare(root, { withBundle: false, minCliVersion: types_1.FACTS_MIN_CLI_VERSION });
+        const skillDir = path_1.default.join(root, 'skills', 'demo');
+        fs_1.default.mkdirSync(skillDir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(skillDir, 'SKILL.md'), `---\nname: demo\ndescription: d\nneeds:\n  - repos.root\n---\n# Demo\n`);
+        const { doctorRegistry } = loadDoctor();
+        const report = doctorRegistry(root);
+        expect(report.structural.some((m) => /needs/i.test(m) && /facts\.json/i.test(m) && /missing/i.test(m))).toBe(true);
+        expect(report.structural.every((m) => !/invalid|unreadable/i.test(m) || !/needs/i.test(m))).toBe(true);
+    });
+    it('reports needs + invalid facts.json as invalid/unreadable, not missing', () => {
+        const root = path_1.default.join(tmp, 'needs-bad-catalog');
+        scaffoldBare(root, {
+            withBundle: false,
+            minCliVersion: types_1.FACTS_MIN_CLI_VERSION,
+            facts: { schemaVersion: 1, facts: {} },
+        });
+        fs_1.default.writeFileSync(path_1.default.join(root, 'facts.json'), '{not-json');
+        const skillDir = path_1.default.join(root, 'skills', 'demo');
+        fs_1.default.mkdirSync(skillDir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(skillDir, 'SKILL.md'), `---\nname: demo\ndescription: d\nneeds:\n  - repos.root\n---\n# Demo\n`);
+        const { doctorRegistry } = loadDoctor();
+        const report = doctorRegistry(root);
+        const needsMsg = report.structural.find((m) => /needs/i.test(m) && /facts\.json/i.test(m));
+        expect(needsMsg).toBeDefined();
+        expect(needsMsg).toMatch(/invalid|unreadable/i);
+        expect(needsMsg).not.toMatch(/\bmissing\b/i);
+    });
+    it('fails structurally when facts present and minCliVersion key absent (RF-4.8)', () => {
+        const root = path_1.default.join(tmp, 'facts-no-min');
+        scaffoldBare(root, {
+            withBundle: false,
+            facts: { schemaVersion: 1, facts: {} },
+        });
+        // scaffoldBare omits minCliVersion when not provided
+        const { doctorRegistry } = loadDoctor();
+        const report = doctorRegistry(root);
+        expect(report.structural.some((m) => /minCliVersion/i.test(m))).toBe(true);
+    });
+    it('rejects empty / non-string root with structural error before path.resolve', () => {
+        const { doctorRegistry } = loadDoctor();
+        expect(doctorRegistry('').structural.some((m) => /root|required|non-empty|string/i.test(m))).toBe(true);
+        expect(doctorRegistry('   ').structural.some((m) => /root|required|non-empty|string/i.test(m))).toBe(true);
+        expect(doctorRegistry(null).structural.some((m) => /root|required|non-empty|string/i.test(m))).toBe(true);
+    });
+    it('reports symlink skill dirs and non-regular SKILL.md as structural (fail closed)', () => {
+        const root = path_1.default.join(tmp, 'skill-symlink');
+        scaffoldBare(root, { withBundle: false, minCliVersion: types_1.FACTS_MIN_CLI_VERSION });
+        const externalSkill = path_1.default.join(tmp, 'external-skill');
+        fs_1.default.mkdirSync(externalSkill, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(externalSkill, 'SKILL.md'), '---\nname: linked\ndescription: d\n---\n');
+        fs_1.default.symlinkSync(externalSkill, path_1.default.join(root, 'skills', 'linked'));
+        const regular = path_1.default.join(root, 'skills', 'regular');
+        fs_1.default.mkdirSync(regular, { recursive: true });
+        const externalMd = path_1.default.join(tmp, 'external-SKILL.md');
+        fs_1.default.writeFileSync(externalMd, '---\nname: regular\ndescription: d\n---\n');
+        fs_1.default.symlinkSync(externalMd, path_1.default.join(regular, 'SKILL.md'));
+        const { doctorRegistry } = loadDoctor();
+        const report = doctorRegistry(root);
+        expect(report.structural.some((m) => /linked/i.test(m) && /symlink|skill/i.test(m))).toBe(true);
+        expect(report.structural.some((m) => /regular/i.test(m) && /SKILL\.md|symlink|regular file/i.test(m))).toBe(true);
+    });
+    // chmod(0) is a POSIX permission seam; on win32 NTFS ACLs often still allow
+    // the creating user to read, so the unreadable path is not reproducible there.
+    (process.platform === 'win32' ? it.skip : it)('reports unreadable SKILL.md as structural (fail closed)', () => {
+        const root = path_1.default.join(tmp, 'skill-unreadable');
+        scaffoldBare(root, { withBundle: false, minCliVersion: types_1.FACTS_MIN_CLI_VERSION });
+        const skillDir = path_1.default.join(root, 'skills', 'locked');
+        fs_1.default.mkdirSync(skillDir, { recursive: true });
+        const skillMd = path_1.default.join(skillDir, 'SKILL.md');
+        fs_1.default.writeFileSync(skillMd, '---\nname: locked\ndescription: d\n---\n');
+        fs_1.default.chmodSync(skillMd, 0);
+        try {
+            const { doctorRegistry } = loadDoctor();
+            const report = doctorRegistry(root);
+            expect(report.structural.some((m) => /locked|SKILL\.md|Cannot read|unreadable/i.test(m))).toBe(true);
+        }
+        finally {
+            fs_1.default.chmodSync(skillMd, 0o644);
+        }
+    });
+    it('does not require facts chapter beyond Capabilities when no facts.json and no needs', () => {
+        const root = path_1.default.join(tmp, 'legacy');
+        scaffoldBare(root, {
+            withBundle: false,
+            handbook: handbook(['hooks | n/a | none']),
+        });
+        const { doctorRegistry } = loadDoctor();
+        const report = doctorRegistry(root);
+        expect(report.structural).toEqual([]);
+    });
+    it('doctor API is path-only and does not require writing-skills (RF-5.1)', () => {
+        const source = fs_1.default.readFileSync(path_1.default.resolve(__dirname, '../../../src/commands/registry/doctor.ts'), 'utf8');
+        expect(source).toMatch(/export function doctorRegistry\(\s*root:\s*string/);
+        expect(source).not.toMatch(/writing-skills/);
+        expect(source).not.toMatch(/writeSkill|writeFileSync.*SKILL/);
+    });
+    it('wires awm registry doctor [name|path] via doctorExitCode', () => {
+        const indexSource = fs_1.default.readFileSync(path_1.default.resolve(__dirname, '../../../src/commands/registry/index.ts'), 'utf8');
+        expect(indexSource).toMatch(/doctorRegistry/);
+        expect(indexSource).toMatch(/doctorExitCode/);
+        expect(indexSource).toMatch(/process\.exit\(doctorExitCode\(/);
+    });
+});