agentic-workflow-manager 3.7.0 → 3.9.0

package/dist/src/commands/context-budget/budget.js

@@ -0,0 +1,112 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_FILE = exports.DEFAULT_FILES = void 0;
+exports.estimateTokens = estimateTokens;
+exports.measure = measure;
+exports.readConfig = readConfig;
+exports.writeConfig = writeConfig;
+exports.checkBudget = checkBudget;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * The feedforward context budget.
+ *
+ * `AGENTS.md`, `CONSTITUTION.md` and `CLAUDE.md` are injected into EVERY agent session
+ * before a single line of code is read, so their size is a per-session tax paid
+ * forever. They grow because curing a lesson is an append and pruning one is a
+ * judgement call nobody is forced to make.
+ *
+ * Prose does not hold this line. Measured on a real repo, `AGENTS.md` went 73KB → 141KB
+ * across 45 revisions and never shrank once, while `harness-retro` already carried an
+ * explicit "merge and prune, never append raw" rule. Adding a second copy of an ignored
+ * rule has no expected effect, so this measures instead.
+ *
+ * It does NOT forbid growth — it makes growth deliberate. First check pins the current
+ * total; later checks report when the files have grown past it. The ways out are pruning
+ * back under, or raising `maxBytes` in a committed diff a human reviews.
+ *
+ * **Where this runs matters as much as what it measures.** It belongs at the last moment
+ * a human is guaranteed to be present — the pre-handoff gate at the end of
+ * `writing-plans`, before execution is handed to subagents. Wired into `awm sensors run`
+ * instead, it would fire during unattended overnight runs and strand the very PR the
+ * user came back expecting. Hence a command, not a sensor.
+ */
+/** Injected into every session by the AWM session hook / context contract. */
+exports.DEFAULT_FILES = ['AGENTS.md', 'CONSTITUTION.md', 'CLAUDE.md'];
+exports.CONFIG_FILE = path_1.default.join('.awm', 'context-budget.json');
+/** Rough but stable: ~4 bytes per token for prose. Reporting only — never a gate input. */
+function estimateTokens(bytes) {
+    return Math.round(bytes / 4 / 1000);
+}
+function measure(cwd, files) {
+    const breakdown = [];
+    let total = 0;
+    for (const f of files) {
+        let s;
+        try {
+            s = fs_1.default.statSync(path_1.default.join(cwd, f));
+        }
+        catch {
+            continue; // a repo need not have all three
+        }
+        if (!s.isFile())
+            continue;
+        total += s.size;
+        breakdown.push({ file: f, bytes: s.size });
+    }
+    return { total, breakdown };
+}
+/**
+ * Read the pinned budget. A malformed or partial config returns null so the caller
+ * re-pins rather than treating an unreadable budget as an absent limit — the quiet
+ * direction of wrong, where the check silently stops checking.
+ */
+function readConfig(cwd) {
+    try {
+        const raw = JSON.parse(fs_1.default.readFileSync(path_1.default.join(cwd, exports.CONFIG_FILE), 'utf-8'));
+        if (typeof raw.maxBytes !== 'number' || !Number.isFinite(raw.maxBytes))
+            return null;
+        return {
+            files: Array.isArray(raw.files) && raw.files.length ? raw.files : exports.DEFAULT_FILES,
+            maxBytes: raw.maxBytes,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeConfig(cwd, config) {
+    fs_1.default.mkdirSync(path_1.default.join(cwd, '.awm'), { recursive: true });
+    const body = {
+        _comment: 'Context budget for files injected into every agent session. Raising maxBytes '
+            + 'is allowed but must be a deliberate, reviewed change — see writing-plans, '
+            + 'Context Budget Gate.',
+        ...config,
+    };
+    fs_1.default.writeFileSync(path_1.default.join(cwd, exports.CONFIG_FILE), JSON.stringify(body, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Measure the injected context against the pinned budget.
+ *
+ * On the first check there is nothing to compare against, so the current total is
+ * pinned and the result is `pinned`. Pinning rather than failing means adopting this
+ * never blocks a repo that is already large — it only stops it getting larger.
+ */
+function checkBudget(cwd) {
+    const config = readConfig(cwd);
+    if (!config) {
+        const { total, breakdown } = measure(cwd, exports.DEFAULT_FILES);
+        writeConfig(cwd, { files: exports.DEFAULT_FILES, maxBytes: total });
+        return { status: 'pinned', totalBytes: total, maxBytes: total, breakdown };
+    }
+    const { total, breakdown } = measure(cwd, config.files);
+    return {
+        status: total > config.maxBytes ? 'over' : 'within',
+        totalBytes: total,
+        maxBytes: config.maxBytes,
+        breakdown,
+    };
+}

package/dist/src/commands/context-budget/index.js

@@ -0,0 +1,58 @@
+"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.registerContextBudgetCommand = registerContextBudgetCommand;
+const picocolors_1 = __importDefault(require("picocolors"));
+const budget_1 = require("./budget");
+const KB = (bytes) => `${(bytes / 1024).toFixed(0)}KB`;
+/**
+ * Exit code. `over` exits 1 so a caller that wants a hard gate can have one — but the
+ * skill that invokes this (writing-plans, Context Budget Gate) deliberately does not
+ * treat it as one. It runs at the last attended moment and presents a choice; blocking
+ * would strand the unattended runs this whole design exists to protect.
+ */
+function exitCodeFor(report) {
+    return report.status === 'over' ? 1 : 0;
+}
+function formatReport(report) {
+    const tokens = `~${(0, budget_1.estimateTokens)(report.totalBytes)}k tokens`;
+    const breakdown = report.breakdown.map(b => `${b.file} ${KB(b.bytes)}`).join(', ');
+    if (report.status === 'pinned') {
+        return `${picocolors_1.default.green('✔')}  Context budget pinned at ${KB(report.totalBytes)} (${tokens} per session).\n`
+            + `   ${breakdown}\n`
+            + `   Saved to ${budget_1.CONFIG_FILE} — commit it. Growth past this point will report here.\n`;
+    }
+    if (report.status === 'within') {
+        return `${picocolors_1.default.green('✔')}  Context budget OK: ${KB(report.totalBytes)} of ${KB(report.maxBytes)} (${tokens} per session).\n`
+            + `   ${breakdown}\n`;
+    }
+    const over = report.totalBytes - report.maxBytes;
+    return `${picocolors_1.default.yellow('⚠')}  Context budget exceeded: ${KB(report.totalBytes)} vs ${KB(report.maxBytes)} `
+        + `(over by ${KB(over)}).\n`
+        + `   ${breakdown}\n`
+        + `   These files are injected into EVERY session — ${tokens} spent before any code is read.\n\n`
+        + `   Decide now, while you are here:\n`
+        + `     1. Prune  — cheapest moment: that context is already loaded and you are\n`
+        + `                 choosing what matters for the work about to start.\n`
+        + `     2. Raise  — edit "maxBytes" in ${budget_1.CONFIG_FILE}; a reviewed decision to keep\n`
+        + `                 paying for this in every future session.\n`
+        + `     3. Accept — proceed and note it in the plan.\n`;
+}
+function registerContextBudgetCommand(program) {
+    program
+        .command('context-budget')
+        .description('check the size of the files injected into every agent session')
+        .option('--json', 'emit the report as JSON')
+        .option('--cwd <path>', 'directory to measure (default: current)')
+        .action((opts) => {
+        const report = (0, budget_1.checkBudget)(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/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

@@ -26,6 +26,8 @@ const miro_1 = require("./core/miro");
 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");
@@ -606,6 +608,8 @@ miroCmd.command('sync <storyMapPath>')
 (0, hooks_1.registerHooksCommand)(program);
 (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/context-budget/budget.test.js

@@ -0,0 +1,100 @@
+"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 budget_1 = require("../../../src/commands/context-budget/budget");
+const context_budget_1 = require("../../../src/commands/context-budget");
+function project(files) {
+    // CLAUDE.md: no test may reach the real ~/.awm. Everything here is a tmpdir.
+    const dir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-budget-'));
+    for (const [name, bytes] of Object.entries(files)) {
+        fs_1.default.writeFileSync(path_1.default.join(dir, name), 'a'.repeat(bytes));
+    }
+    return dir;
+}
+describe('checkBudget', () => {
+    const dirs = [];
+    const make = (f) => { const d = project(f); dirs.push(d); return d; };
+    afterAll(() => dirs.forEach(d => fs_1.default.rmSync(d, { recursive: true, force: true })));
+    it('pins the current total on the first check instead of failing', () => {
+        // Adopting this must never block a repo that is already large — it only stops
+        // it getting larger. A first-run failure would make it unadoptable exactly
+        // where it is most needed.
+        const dir = make({ 'AGENTS.md': 5000, 'CONSTITUTION.md': 3000 });
+        const report = (0, budget_1.checkBudget)(dir);
+        expect(report.status).toBe('pinned');
+        expect(report.totalBytes).toBe(8000);
+        expect((0, budget_1.readConfig)(dir).maxBytes).toBe(8000);
+    });
+    it('reports over once the files grow past the pin', () => {
+        const dir = make({ 'AGENTS.md': 5000 });
+        (0, budget_1.checkBudget)(dir); // pin at 5000
+        fs_1.default.appendFileSync(path_1.default.join(dir, 'AGENTS.md'), 'b'.repeat(2000));
+        const report = (0, budget_1.checkBudget)(dir);
+        expect(report.status).toBe('over');
+        expect(report.totalBytes).toBe(7000);
+        expect(report.maxBytes).toBe(5000);
+    });
+    it('goes quiet again once pruned back under budget', () => {
+        const dir = make({ 'AGENTS.md': 5000 });
+        (0, budget_1.checkBudget)(dir);
+        fs_1.default.writeFileSync(path_1.default.join(dir, 'AGENTS.md'), 'a'.repeat(4000));
+        expect((0, budget_1.checkBudget)(dir).status).toBe('within');
+    });
+    it('does not re-pin on later checks, so the budget is a real ratchet', () => {
+        // If a later check re-pinned, growth would always look like the new normal and
+        // the budget would never mean anything.
+        const dir = make({ 'AGENTS.md': 5000 });
+        (0, budget_1.checkBudget)(dir);
+        fs_1.default.appendFileSync(path_1.default.join(dir, 'AGENTS.md'), 'b'.repeat(9000));
+        (0, budget_1.checkBudget)(dir);
+        expect((0, budget_1.readConfig)(dir).maxBytes).toBe(5000);
+    });
+    it('counts only the files that exist', () => {
+        const dir = make({ 'AGENTS.md': 1000 }); // no CONSTITUTION.md, no CLAUDE.md
+        const report = (0, budget_1.checkBudget)(dir);
+        expect(report.totalBytes).toBe(1000);
+        expect(report.breakdown.map(b => b.file)).toEqual(['AGENTS.md']);
+    });
+    it('re-pins when the config is unreadable rather than treating it as no limit', () => {
+        // An unparseable budget must not silently disable the check — that is the quiet
+        // direction of wrong, where it stops checking and still reports success.
+        const dir = make({ 'AGENTS.md': 2000 });
+        fs_1.default.mkdirSync(path_1.default.join(dir, '.awm'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(dir, budget_1.CONFIG_FILE), '{ not json');
+        const report = (0, budget_1.checkBudget)(dir);
+        expect(report.status).toBe('pinned');
+        expect((0, budget_1.readConfig)(dir).maxBytes).toBe(2000);
+    });
+    it('honours a custom file list from the config', () => {
+        const dir = make({ 'AGENTS.md': 1000, 'OTHER.md': 500 });
+        fs_1.default.mkdirSync(path_1.default.join(dir, '.awm'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(dir, budget_1.CONFIG_FILE), JSON.stringify({ files: ['OTHER.md'], maxBytes: 100 }));
+        const report = (0, budget_1.checkBudget)(dir);
+        expect(report.totalBytes).toBe(500);
+        expect(report.status).toBe('over');
+    });
+});
+describe('reporting', () => {
+    it('exits non-zero only when over budget', () => {
+        expect((0, context_budget_1.exitCodeFor)({ status: 'over', totalBytes: 2, maxBytes: 1, breakdown: [] })).toBe(1);
+        expect((0, context_budget_1.exitCodeFor)({ status: 'within', totalBytes: 1, maxBytes: 2, breakdown: [] })).toBe(0);
+        expect((0, context_budget_1.exitCodeFor)({ status: 'pinned', totalBytes: 1, maxBytes: 1, breakdown: [] })).toBe(0);
+    });
+    it('offers the three choices when over, since this runs while a human is present', () => {
+        const out = (0, context_budget_1.formatReport)({
+            status: 'over',
+            totalBytes: 227_000,
+            maxBytes: 224_000,
+            breakdown: [{ file: 'AGENTS.md', bytes: 145_000 }],
+        });
+        expect(out).toContain('Prune');
+        expect(out).toContain('Raise');
+        expect(out).toContain('Accept');
+        expect(out).toMatch(/~5[0-9]k tokens/);
+    });
+});

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.7.0",
+  "version": "3.9.0",
   "main": "dist/src/index.js",
   "bin": {
     "awm": "./dist/src/index.js"