agentic-workflow-manager 3.8.0 → 3.9.0

package/dist/src/commands/preflight/checks.js

@@ -0,0 +1,123 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preflight = preflight;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const status_1 = require("../sensors/status");
+const init_1 = require("../sensors/init");
+const MANIFEST = path_1.default.join('.awm', 'sensors.json');
+/**
+ * The agent needs project context delivered every session. A repo with neither file
+ * hands every agent — and every teammate's agent — a blank slate.
+ */
+function checkContext(cwd) {
+    const present = ['AGENTS.md', 'CLAUDE.md', 'CONSTITUTION.md']
+        .filter(f => fs_1.default.existsSync(path_1.default.join(cwd, f)));
+    if (present.length === 0) {
+        return {
+            id: 'context',
+            ok: false,
+            detail: 'no AGENTS.md, CLAUDE.md or CONSTITUTION.md',
+            remedy: 'run the project-context-init skill (AGENTS.md) or project-constitution (CONSTITUTION.md)',
+        };
+    }
+    return { id: 'context', ok: true, detail: present.join(', ') };
+}
+function readManifest(cwd) {
+    try {
+        return JSON.parse(fs_1.default.readFileSync(path_1.default.join(cwd, MANIFEST), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A repo may legitimately have no sensors — but it has to SAY so, in a committed file.
+ *
+ * That is why opting out requires a manifest with its sensors disabled rather than
+ * simply having no manifest. "We decided not to gate this repo" and "nobody ever ran
+ * `awm sensors init`" look identical from the outside, and on a team the second one is
+ * the common case. Requiring the manifest turns the decision into a reviewable diff.
+ */
+function checkManifest(cwd, manifest) {
+    if (!fs_1.default.existsSync(path_1.default.join(cwd, MANIFEST))) {
+        return {
+            id: 'manifest',
+            ok: false,
+            detail: 'no .awm/sensors.json',
+            remedy: 'run `awm sensors init` (to opt out deliberately, init and set every sensor '
+                + '`"enabled": false` — an unconfigured repo and a deliberate opt-out must not look alike)',
+        };
+    }
+    if (!manifest) {
+        return {
+            id: 'manifest',
+            ok: false,
+            detail: '.awm/sensors.json is not valid JSON',
+            remedy: 'fix or regenerate it with `awm sensors init`',
+        };
+    }
+    const total = Object.keys(manifest.sensors ?? {}).length;
+    const enabled = Object.values(manifest.sensors ?? {}).filter(s => s.enabled !== false).length;
+    return {
+        id: 'manifest',
+        ok: true,
+        detail: enabled === 0 ? `pack ${manifest.pack}, all ${total} sensors disabled (deliberate opt-out)`
+            : `pack ${manifest.pack}, ${enabled}/${total} sensors enabled`,
+    };
+}
+/** Every enabled sensor's command must resolve. This is the check nothing was calling. */
+function checkTools(cwd) {
+    const status = (0, status_1.computeSensorStatus)(cwd);
+    if (status.overall === 'NOT_CONFIGURED') {
+        return { id: 'tools', ok: false, detail: 'no manifest to check', remedy: 'run `awm sensors init`' };
+    }
+    const broken = Object.entries(status.checks).filter(([, c]) => !c.ok);
+    if (broken.length > 0) {
+        return {
+            id: 'tools',
+            ok: false,
+            detail: broken.map(([name, c]) => `${name}: ${c.detail}`).join('; '),
+            remedy: 'install the missing tools/configs, or disable those sensors deliberately',
+        };
+    }
+    return { id: 'tools', ok: true, detail: `${Object.keys(status.checks).length} sensor(s) runnable` };
+}
+/**
+ * A manifest pinned to `generic` on a tree that clearly has a stack means the real
+ * sensors for that stack are simply absent — the gate runs, reports green, and has
+ * checked almost nothing. `runSensors` self-heals this at run time via `reconcilePack`,
+ * but only when a registry is reachable; saying it out loud here costs nothing.
+ */
+function checkPack(cwd, manifest) {
+    if (!manifest)
+        return { id: 'pack', ok: true, detail: 'skipped (no manifest)' };
+    const detection = (0, init_1.detectStack)(cwd);
+    if (manifest.pack === 'generic' && detection.pack !== 'generic') {
+        return {
+            id: 'pack',
+            ok: false,
+            detail: `manifest on 'generic' but the tree looks like '${detection.pack}' (${detection.indicators.join(', ')})`,
+            remedy: 'run `awm sensors init` to pick up the real pack for this stack',
+        };
+    }
+    return { id: 'pack', ok: true, detail: `${manifest.pack} matches the detected stack` };
+}
+function preflight(cwd = process.cwd()) {
+    const manifest = readManifest(cwd);
+    const manifestExists = fs_1.default.existsSync(path_1.default.join(cwd, MANIFEST));
+    const checks = [
+        checkContext(cwd),
+        checkManifest(cwd, manifest),
+        // Skipped when there is no manifest: reporting "tools broken" on a repo that was
+        // never set up buries the one thing the operator needs to read.
+        ...(manifestExists ? [checkTools(cwd), checkPack(cwd, manifest)] : []),
+    ];
+    const status = !manifestExists ? 'not_configured'
+        : checks.every(c => c.ok) ? 'ready'
+            : 'degraded';
+    return { status, checks };
+}

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

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exitCodeFor = exitCodeFor;
+exports.formatReport = formatReport;
+exports.registerPreflightCommand = registerPreflightCommand;
+const picocolors_1 = __importDefault(require("picocolors"));
+const checks_1 = require("./checks");
+/**
+ * Exit code. Anything but `ready` exits 1.
+ *
+ * Unlike `awm sensors run` — which exits 0 on `not_certified` because exit 2 is a
+ * blocking error in Claude Code hooks — preflight is never a hook. It is invoked
+ * explicitly by a phase gate, so the exit code can carry the verdict and the caller
+ * does not have to remember to read a field out of JSON.
+ */
+function exitCodeFor(report) {
+    return report.status === 'ready' ? 0 : 1;
+}
+function formatReport(report) {
+    const lines = report.checks.map(c => `  ${c.ok ? picocolors_1.default.green('✔') : picocolors_1.default.red('✘')}  ${c.id.padEnd(9)} ${c.detail}`
+        + (c.remedy ? `\n       ${picocolors_1.default.dim('→ ' + c.remedy)}` : ''));
+    if (report.status === 'ready') {
+        return `${picocolors_1.default.green('✔')}  Harness ready — this project can be gated.\n${lines.join('\n')}\n`;
+    }
+    const headline = report.status === 'not_configured'
+        ? `${picocolors_1.default.red('✘')}  AWM is not configured in this project.`
+        : `${picocolors_1.default.red('✘')}  Harness degraded — it declares sensors it cannot run.`;
+    return `${headline}\n${lines.join('\n')}\n\n`
+        + `   ${picocolors_1.default.bold('Do not hand this off to an unattended run.')} Every quality phase downstream\n`
+        + `   (implementer, reviewers, post-qa) consumes \`awm sensors run\`. With the harness in\n`
+        + `   this state the gate reports on checks that never ran, and nobody finds out until a\n`
+        + `   bad change is already merged.\n`;
+}
+function registerPreflightCommand(program) {
+    program
+        .command('preflight')
+        .description('verify the project harness can actually gate before development starts')
+        .option('--json', 'emit the report as JSON')
+        .option('--cwd <path>', 'project directory to check (default: current)')
+        .action((opts) => {
+        const report = (0, checks_1.preflight)(opts.cwd ?? process.cwd());
+        process.stdout.write(opts.json ? JSON.stringify(report, null, 2) + '\n' : formatReport(report));
+        const code = exitCodeFor(report);
+        if (code !== 0)
+            process.exit(code);
+    });
+}

package/dist/src/index.js

@@ -27,6 +27,7 @@ const hooks_1 = require("./commands/hooks");
 const sensors_1 = require("./commands/sensors");
 const ledger_1 = require("./commands/ledger");
 const context_budget_1 = require("./commands/context-budget");
+const preflight_1 = require("./commands/preflight");
 const doctor_1 = require("./commands/doctor");
 const backup_1 = require("./commands/backup");
 const init_1 = require("./commands/init");
@@ -608,6 +609,7 @@ miroCmd.command('sync <storyMapPath>')
 (0, sensors_1.registerSensorsCommand)(program);
 (0, ledger_1.registerLedgerCommand)(program);
 (0, context_budget_1.registerContextBudgetCommand)(program);
+(0, preflight_1.registerPreflightCommand)(program);
 (0, doctor_1.registerDoctorCommand)(program);
 (0, backup_1.registerBackupCommand)(program);
 (0, init_1.registerInitCommand)(program);

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

@@ -0,0 +1,123 @@
+"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 checks_1 = require("../../../src/commands/preflight/checks");
+const preflight_1 = require("../../../src/commands/preflight");
+/** CLAUDE.md: no test may reach the real ~/.awm. Everything here is a tmpdir. */
+function project(opts = {}) {
+    const dir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-preflight-'));
+    for (const f of opts.context ?? ['AGENTS.md'])
+        fs_1.default.writeFileSync(path_1.default.join(dir, f), '# ctx\n');
+    for (const f of opts.files ?? []) {
+        fs_1.default.mkdirSync(path_1.default.dirname(path_1.default.join(dir, f)), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(dir, f), '');
+    }
+    for (const b of opts.bins ?? []) {
+        fs_1.default.mkdirSync(path_1.default.join(dir, 'node_modules', '.bin'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(dir, 'node_modules', '.bin', b), '');
+    }
+    if (opts.manifest !== undefined) {
+        fs_1.default.mkdirSync(path_1.default.join(dir, '.awm'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(dir, '.awm', 'sensors.json'), typeof opts.manifest === 'string' ? opts.manifest : JSON.stringify(opts.manifest));
+    }
+    return dir;
+}
+const dirs = [];
+const make = (o) => { const d = project(o); dirs.push(d); return d; };
+afterAll(() => dirs.forEach(d => fs_1.default.rmSync(d, { recursive: true, force: true })));
+const check = (r, id) => r.checks.find(c => c.id === id);
+describe('preflight', () => {
+    it('reports not_configured when no sensor manifest exists', () => {
+        // The team-rollout case: a developer clones the repo and never runs
+        // `awm sensors init`. Today nothing notices until an unattended run is already
+        // in flight and every quality phase is consuming a gate that certifies nothing.
+        const dir = make();
+        const report = (0, checks_1.preflight)(dir);
+        expect(report.status).toBe('not_configured');
+        expect(check(report, 'manifest').ok).toBe(false);
+    });
+    it('keeps not_configured and degraded apart', () => {
+        // "You never set this up" and "you set it up and it broke" need different
+        // remedies. Collapsing them is how an absent check reads as a passing one.
+        const never = make();
+        const broken = make({
+            manifest: { pack: 'js-ts', sensors: { lint: { cmd: 'npx eslint .' } } }, // no local eslint
+        });
+        expect((0, checks_1.preflight)(never).status).toBe('not_configured');
+        expect((0, checks_1.preflight)(broken).status).toBe('degraded');
+    });
+    it('is ready when the declared sensors can actually run', () => {
+        const dir = make({
+            manifest: { pack: 'js-ts', sensors: { lint: { cmd: 'npx eslint .' } } },
+            bins: ['eslint'],
+            files: ['package.json'],
+        });
+        const report = (0, checks_1.preflight)(dir);
+        expect(report.status).toBe('ready');
+        expect((0, preflight_1.exitCodeFor)(report)).toBe(0);
+    });
+    it('catches a sensor whose tool is not installed locally', () => {
+        // This is the check that existed and nothing in the flow was calling.
+        const dir = make({
+            manifest: { pack: 'js-ts', sensors: { lint: { cmd: 'npx eslint .' } } },
+            files: ['package.json'],
+        });
+        const report = (0, checks_1.preflight)(dir);
+        expect(report.status).toBe('degraded');
+        expect(check(report, 'tools').detail).toContain('eslint');
+    });
+    it('accepts a deliberate opt-out, but only when it is written down', () => {
+        // A repo may legitimately have no sensors — it just has to SAY so in a committed
+        // file, so "we decided not to gate this" cannot be mistaken for "nobody set it up".
+        const optedOut = make({
+            manifest: { pack: 'generic', sensors: { security: { cmd: 'semgrep .', enabled: false } } },
+        });
+        const report = (0, checks_1.preflight)(optedOut);
+        expect(report.status).toBe('ready');
+        expect(check(report, 'manifest').detail).toContain('opt-out');
+    });
+    it('flags a manifest stuck on generic while the tree has a real stack', () => {
+        // The gate would run, report green, and have checked almost nothing.
+        const dir = make({
+            manifest: { pack: 'generic', sensors: {} },
+            files: ['package.json'],
+        });
+        const report = (0, checks_1.preflight)(dir);
+        expect(report.status).toBe('degraded');
+        expect(check(report, 'pack').ok).toBe(false);
+    });
+    it('flags a repo with no context contract at all', () => {
+        const dir = make({
+            context: [],
+            manifest: { pack: 'generic', sensors: {} },
+        });
+        expect(check((0, checks_1.preflight)(dir), 'context').ok).toBe(false);
+    });
+    it('treats an unparseable manifest as a failure, not as absent', () => {
+        const dir = make({ manifest: '{ not json' });
+        const report = (0, checks_1.preflight)(dir);
+        expect(report.status).toBe('degraded');
+        expect(check(report, 'manifest').detail).toContain('not valid JSON');
+    });
+    it('exits non-zero for anything but ready, so the caller need not parse JSON', () => {
+        // Unlike `awm sensors run` — which exits 0 on not_certified because exit 2 blocks
+        // Claude Code hooks — preflight is never a hook, so the verdict rides the exit code
+        // instead of depending on every agent remembering to read a field.
+        expect((0, preflight_1.exitCodeFor)({ status: 'not_configured', checks: [] })).toBe(1);
+        expect((0, preflight_1.exitCodeFor)({ status: 'degraded', checks: [] })).toBe(1);
+        expect((0, preflight_1.exitCodeFor)({ status: 'ready', checks: [] })).toBe(0);
+    });
+    it('tells the operator not to hand a broken harness to an unattended run', () => {
+        const out = (0, preflight_1.formatReport)({
+            status: 'not_configured',
+            checks: [{ id: 'manifest', ok: false, detail: 'no .awm/sensors.json', remedy: 'run `awm sensors init`' }],
+        });
+        expect(out).toContain('unattended');
+        expect(out).toContain('awm sensors init');
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-workflow-manager",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "main": "dist/src/index.js",
   "bin": {
     "awm": "./dist/src/index.js"