agentic-workflow-manager 3.6.0 → 3.8.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/sensors/changed.js

@@ -0,0 +1,95 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.changedFiles = changedFiles;
+exports.applyChangedCmd = applyChangedCmd;
+exports.filterByExtension = filterByExtension;
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+function git(args, cwd) {
+    return (0, child_process_1.execFileSync)('git', args, {
+        cwd,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+}
+/**
+ * The default comparison point. `merge-base HEAD <base>` — not `base` directly —
+ * so a branch that is merely *behind* its base does not report every file the base
+ * moved on as "changed" by this branch.
+ */
+function mergeBase(base, cwd) {
+    return git(['merge-base', 'HEAD', base], cwd).trim();
+}
+/**
+ * Files this working tree changed relative to `base`.
+ *
+ * Deliberately a union of four sources: the committed diff since the merge base,
+ * plus staged, unstaged and untracked files. A sensor gate runs mid-work, where the
+ * interesting edits are usually not committed yet — a committed-only diff would scope
+ * the run to a stale set and certify files nobody is editing.
+ *
+ * Untracked files are included but ignored files are not (`--exclude-standard`), so
+ * `node_modules` and build output never enter the scope.
+ *
+ * Never throws: a failure to resolve the scope returns `error`, and the caller
+ * degrades to the unscoped command rather than guessing at a narrower one.
+ */
+function changedFiles(cwd, base = 'HEAD') {
+    let out = [];
+    try {
+        // `HEAD` means "everything not yet committed" — no merge-base needed, and it
+        // is the right default for a gate that runs before the work is committed.
+        if (base !== 'HEAD') {
+            const from = mergeBase(base, cwd);
+            out = out.concat(git(['diff', '--name-only', '--diff-filter=d', from, 'HEAD'], cwd).split('\n'));
+        }
+        out = out.concat(git(['diff', '--name-only', '--diff-filter=d', 'HEAD'], cwd).split('\n'));
+        out = out.concat(git(['diff', '--name-only', '--diff-filter=d', '--cached'], cwd).split('\n'));
+        out = out.concat(git(['ls-files', '--others', '--exclude-standard'], cwd).split('\n'));
+    }
+    catch (e) {
+        return { files: [], error: e.message.split('\n')[0] };
+    }
+    const files = Array.from(new Set(out.map(s => s.trim()).filter(Boolean))).sort();
+    return { files };
+}
+/**
+ * Quote a path for a shell command line. Sensor commands are strings run through a
+ * shell, so a path with a space or a quote in it would otherwise split into two
+ * arguments — or, worse, end the quoting and let the rest of the name be read as
+ * shell syntax. Single quotes with the `'\''` escape are the only form POSIX shells
+ * treat as fully literal.
+ */
+function shellQuote(file) {
+    return `'${file.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Substitute the file list into a `changedCmd` template.
+ *
+ * The template must contain `{files}`. A template without it would silently run over
+ * the whole repo while the output claimed the run was scoped, so that case is
+ * rejected by the caller rather than papered over here.
+ */
+function applyChangedCmd(template, files) {
+    return template.replace('{files}', files.map(shellQuote).join(' '));
+}
+/**
+ * Narrow the changed set to what a given sensor can be handed.
+ *
+ * The changed set is everything the tree touched — a README, a lockfile, a PNG. The
+ * tools do not shrug those off: eslint given a `.md` fails rather than skipping it,
+ * so an unfiltered scoped run would turn "you edited the docs" into a red gate.
+ *
+ * Case-insensitive because Windows and macOS checkouts routinely carry `.TS`/`.Ts`,
+ * and a case-sensitive match would silently drop those files from the scope — the
+ * quiet direction of wrong, where the sensor reports clean over files it never saw.
+ */
+function filterByExtension(files, extensions) {
+    if (!extensions || extensions.length === 0)
+        return files;
+    const allowed = new Set(extensions.map(e => e.toLowerCase()));
+    return files.filter(f => allowed.has(path_1.default.extname(f).toLowerCase()));
+}

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

@@ -27,8 +27,13 @@ function registerSensorsCommand(program) {
         .option('--fast', 'run fast sensors only (tsc, lint)')
         .option('--slow', 'run slow sensors only (semgrep, mutation)')
         .option('--all', 'run all sensors regardless of speed')
+        .option('--changed', 'scope sensors that support it to the files changed vs --base')
+        .option('--base <ref>', 'comparison point for --changed (default: HEAD, i.e. uncommitted work)')
         .action(async (opts) => {
-        const output = await (0, run_1.runSensors)({ fast: opts.fast, slow: opts.slow, all: opts.all });
+        const output = await (0, run_1.runSensors)({
+            fast: opts.fast, slow: opts.slow, all: opts.all,
+            changed: opts.changed, base: opts.base,
+        });
         // Emit the verdict ALWAYS — an empty `sensors` with overall:'not_certified'
         // must be visible, never a silent exit-0 that reads as "clean".
         process.stdout.write(JSON.stringify(output, null, 2) + '\n');

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

@@ -68,6 +68,14 @@ function readPackDefaults(pack, registryRoot, cwd) {
             entry.fast = def.fast;
         if (def.enabled !== undefined)
             entry.enabled = def.enabled;
+        // Carried through verbatim: without these in the written manifest, a pack can
+        // declare a sensor scopable and `--changed` would silently run it in full —
+        // the flag would look supported and do nothing. `{{SOURCE_DIRS}}` is not
+        // substituted here on purpose: a scoped command takes an explicit file list.
+        if (def.changedCmd)
+            entry.changedCmd = def.changedCmd;
+        if (def.changedExtensions)
+            entry.changedExtensions = def.changedExtensions;
         sensors[name] = entry;
     }
     return sensors;

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

@@ -18,6 +18,7 @@ const semgrep_1 = require("./formatters/semgrep");
 const generic_1 = require("./formatters/generic");
 const test_1 = require("./formatters/test");
 const baseline_1 = require("./baseline");
+const changed_1 = require("./changed");
 const init_1 = require("./init");
 const registries_1 = require("../../core/registries");
 const MANIFEST_FILE = '.awm/sensors.json';
@@ -254,6 +255,19 @@ async function runSensors(opts = {}) {
     // ones (essential on repos with a large pre-existing baseline). Absent file or
     // --ignore-baseline → every finding counts (backward-compatible).
     const baseline = opts.ignoreBaseline ? null : (0, baseline_1.readBaseline)(cwd);
+    // A scoped run must never define the accepted set. `buildBaseline` snapshots the
+    // findings of the run it is given, so baselining a `--changed` run would write a
+    // baseline covering only the touched files and silently drop every accepted
+    // finding elsewhere in the repo — which then reports as NEW on the next full run.
+    // The two flags only ever meet by mistake, so refuse rather than pick a meaning.
+    if (opts.changed && opts.ignoreBaseline) {
+        throw new Error('refusing to combine --changed with a baseline capture: a partial run cannot define '
+            + 'the accepted set (it would drop every accepted finding outside the diff). '
+            + 'Run `awm sensors baseline` without --changed.');
+    }
+    // Resolved once for the whole run, not per sensor: `git` is cheap but the answer
+    // must be identical across sensors, or two of them scope to different file sets.
+    const changed = opts.changed ? (0, changed_1.changedFiles)(cwd, opts.base ?? 'HEAD') : null;
     // Sensors are independent processes over the same tree, so they run
     // concurrently rather than one-after-another: wall clock becomes the slowest
     // sensor instead of the sum of all of them. Tasks are built — and dispatched —
@@ -274,11 +288,41 @@ async function runSensors(opts = {}) {
             tasks.push(settled({ name, status: 'inconclusive', errors: [], skipReason: 'no cmd configured' }));
             continue;
         }
-        const cmd = config.cmd;
+        // Scoping applies only where the pack opted in AND the scope resolved. Any
+        // other combination falls back to the full command: slower, never wrong.
+        let cmd = config.cmd;
+        let scope;
+        if (changed && !changed.error && config.changedCmd) {
+            if (!config.changedCmd.includes('{files}')) {
+                // Running the template as-is would cover the whole repo while the
+                // result claimed to be scoped — a mislabel, not a slow path.
+                tasks.push(settled({
+                    name,
+                    status: 'inconclusive',
+                    errors: [],
+                    skipReason: 'changedCmd has no {files} placeholder',
+                }));
+                continue;
+            }
+            const inScope = (0, changed_1.filterByExtension)(changed.files, config.changedExtensions);
+            if (inScope.length === 0) {
+                tasks.push(settled({
+                    name,
+                    status: 'skipped',
+                    errors: [],
+                    skipReason: 'no changed files in scope',
+                    scope: 'changed',
+                }));
+                continue;
+            }
+            cmd = (0, changed_1.applyChangedCmd)(config.changedCmd, inScope);
+            scope = 'changed';
+        }
         const timeout = config.timeout ?? (isFast ? DEFAULT_FAST_TIMEOUT : DEFAULT_SLOW_TIMEOUT);
         tasks.push(async () => {
             const result = await runSensor(name, cmd, timeout, cwd);
-            return baseline ? applyBaseline(result, baseline[name]) : result;
+            const scoped = scope ? { ...result, scope } : result;
+            return baseline ? applyBaseline(scoped, baseline[name]) : scoped;
         });
     }
     const results = await pooled(tasks, resolveConcurrency(activeManifest, tasks.length));
@@ -298,5 +342,10 @@ async function runSensors(opts = {}) {
         sensors: results,
         overall,
         ...(reconciled.upgradedFrom ? { packUpgraded: `${reconciled.upgradedFrom}→${activeManifest.pack}` } : {}),
+        // Always emitted on a --changed run, including when the scope failed to
+        // resolve: a green that came back from an unscoped fallback and a green from a
+        // genuinely scoped run are different claims, and the caller cannot tell them
+        // apart from the sensor list alone.
+        ...(changed ? { changedScope: { files: changed.files.length, ...(changed.error ? { error: changed.error } : {}) } } : {}),
     };
 }

package/dist/src/index.js

@@ -26,6 +26,7 @@ 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 doctor_1 = require("./commands/doctor");
 const backup_1 = require("./commands/backup");
 const init_1 = require("./commands/init");
@@ -606,6 +607,7 @@ 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, 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/sensors/changed.test.js

@@ -0,0 +1,114 @@
+"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 changed_1 = require("../../../src/commands/sensors/changed");
+/** A throwaway repo. Real git, not a mock: the whole value of this module is that its
+ *  understanding of "changed" matches git's, which a mock would define into existence. */
+function repo() {
+    const dir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-changed-'));
+    const run = (args) => (0, child_process_1.execFileSync)('git', args, { cwd: dir, stdio: 'ignore' });
+    run(['init', '-q']);
+    run(['config', 'user.email', 'test@example.com']);
+    run(['config', 'user.name', 'test']);
+    fs_1.default.writeFileSync(path_1.default.join(dir, 'base.ts'), 'export const a = 1;\n');
+    run(['add', 'base.ts']);
+    run(['commit', '-qm', 'base']);
+    return dir;
+}
+describe('changedFiles', () => {
+    const dirs = [];
+    const make = () => { const d = repo(); dirs.push(d); return d; };
+    afterAll(() => dirs.forEach(d => fs_1.default.rmSync(d, { recursive: true, force: true })));
+    it('sees unstaged, staged and untracked files, not just committed ones', () => {
+        // The gate runs mid-work, before anything is committed. A committed-only diff
+        // would scope the run to a stale set and certify files nobody is editing —
+        // exactly the files least likely to be broken right now.
+        const dir = make();
+        fs_1.default.appendFileSync(path_1.default.join(dir, 'base.ts'), 'export const b = 2;\n'); // unstaged
+        fs_1.default.writeFileSync(path_1.default.join(dir, 'staged.ts'), 'export const c = 3;\n');
+        (0, child_process_1.execFileSync)('git', ['add', 'staged.ts'], { cwd: dir, stdio: 'ignore' }); // staged
+        fs_1.default.writeFileSync(path_1.default.join(dir, 'untracked.ts'), 'export const d = 4;\n'); // untracked
+        expect((0, changed_1.changedFiles)(dir).files).toEqual(['base.ts', 'staged.ts', 'untracked.ts']);
+    });
+    it('excludes gitignored files so build output never enters the scope', () => {
+        const dir = make();
+        fs_1.default.writeFileSync(path_1.default.join(dir, '.gitignore'), 'dist/\n');
+        fs_1.default.mkdirSync(path_1.default.join(dir, 'dist'));
+        fs_1.default.writeFileSync(path_1.default.join(dir, 'dist', 'bundle.js'), 'noise');
+        expect((0, changed_1.changedFiles)(dir).files).not.toContain('dist/bundle.js');
+    });
+    it('omits deleted files — a sensor cannot read a path that is gone', () => {
+        const dir = make();
+        fs_1.default.rmSync(path_1.default.join(dir, 'base.ts'));
+        expect((0, changed_1.changedFiles)(dir).files).not.toContain('base.ts');
+    });
+    it('compares against the merge base, not the branch tip', () => {
+        // Guards the case where the branch is merely BEHIND its base. Diffing against
+        // the tip would report every file the base moved on as "changed by this
+        // branch", scoping the run to files this branch never touched.
+        const dir = make();
+        const run = (args) => (0, child_process_1.execFileSync)('git', args, { cwd: dir, stdio: 'ignore' });
+        run(['checkout', '-qb', 'feature']);
+        fs_1.default.writeFileSync(path_1.default.join(dir, 'mine.ts'), 'export const mine = 1;\n');
+        run(['add', 'mine.ts']);
+        run(['commit', '-qm', 'mine']);
+        // main moves on independently, so `feature` is behind it.
+        run(['checkout', '-q', 'master']);
+        fs_1.default.writeFileSync(path_1.default.join(dir, 'theirs.ts'), 'export const theirs = 1;\n');
+        run(['add', 'theirs.ts']);
+        run(['commit', '-qm', 'theirs']);
+        run(['checkout', '-q', 'feature']);
+        const files = (0, changed_1.changedFiles)(dir, 'master').files;
+        expect(files).toContain('mine.ts');
+        expect(files).not.toContain('theirs.ts');
+    });
+    it('reports an error instead of an empty scope when git cannot answer', () => {
+        // An empty file list and a failed lookup are the same value structurally but
+        // opposite in meaning: one says "nothing to check", the other "I do not know".
+        // Collapsing them would silently scope a run to zero files and report clean.
+        const dir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-nogit-'));
+        dirs.push(dir);
+        const res = (0, changed_1.changedFiles)(dir);
+        expect(res.error).toBeDefined();
+        expect(res.files).toEqual([]);
+    });
+});
+describe('applyChangedCmd', () => {
+    it('substitutes the file list into the template', () => {
+        expect((0, changed_1.applyChangedCmd)('eslint --format json {files}', ['a.ts', 'b.ts']))
+            .toBe(`eslint --format json 'a.ts' 'b.ts'`);
+    });
+    it('quotes paths so a space cannot split one argument into two', () => {
+        expect((0, changed_1.applyChangedCmd)('eslint {files}', ['my dir/a.ts']))
+            .toBe(`eslint 'my dir/a.ts'`);
+    });
+    it("escapes a single quote in a path instead of ending the quoting", () => {
+        // Without the '\'' form the rest of the filename would be read as shell syntax.
+        expect((0, changed_1.applyChangedCmd)('eslint {files}', ["it's.ts"]))
+            .toBe(`eslint 'it'\\''s.ts'`);
+    });
+});
+describe('filterByExtension', () => {
+    it('drops files the sensor cannot be handed', () => {
+        // Editing a README must not turn the lint gate red: eslint given a .md fails
+        // rather than skipping it.
+        expect((0, changed_1.filterByExtension)(['src/a.ts', 'README.md', 'logo.png'], ['.ts']))
+            .toEqual(['src/a.ts']);
+    });
+    it('matches extensions case-insensitively', () => {
+        // Windows and macOS checkouts carry .TS. A case-sensitive match would drop them
+        // from the scope silently — the sensor would report clean over files it never saw.
+        expect((0, changed_1.filterByExtension)(['src/A.TS'], ['.ts'])).toEqual(['src/A.TS']);
+    });
+    it('passes everything through when the sensor declares no filter', () => {
+        const files = ['a.ts', 'b.md'];
+        expect((0, changed_1.filterByExtension)(files, undefined)).toEqual(files);
+        expect((0, changed_1.filterByExtension)(files, [])).toEqual(files);
+    });
+});

package/dist/tests/commands/sensors/run-changed.test.js

@@ -0,0 +1,136 @@
+"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 mockRunCommand = jest.fn();
+jest.mock('../../../src/commands/sensors/exec', () => ({
+    runCommand: (...args) => mockRunCommand(...args),
+}));
+const mockChangedFiles = jest.fn();
+jest.mock('../../../src/commands/sensors/changed', () => {
+    const actual = jest.requireActual('../../../src/commands/sensors/changed');
+    return { ...actual, changedFiles: (...args) => mockChangedFiles(...args) };
+});
+const { ok } = require('./exec-fixtures');
+function project(sensors) {
+    const dir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-changed-run-'));
+    fs_1.default.mkdirSync(path_1.default.join(dir, '.awm'), { recursive: true });
+    fs_1.default.writeFileSync(path_1.default.join(dir, '.awm', 'sensors.json'), JSON.stringify({ pack: 'js-ts', sensors }));
+    return dir;
+}
+/** The two sensors that matter: one that opted into scoping, one that cannot. */
+const LINT = { fast: true, cmd: 'eslint --format json .', changedCmd: 'eslint --format json {files}' };
+const TYPECHECK = { fast: true, cmd: 'tsc --noEmit' };
+describe('runSensors --changed', () => {
+    let dir;
+    let prevAwmHome;
+    let fakeAwmHome;
+    beforeEach(() => {
+        jest.resetModules();
+        mockRunCommand.mockReset();
+        mockChangedFiles.mockReset();
+        mockRunCommand.mockResolvedValue(ok(''));
+        // CLAUDE.md: no test may reach the real ~/.awm.
+        fakeAwmHome = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-home-'));
+        prevAwmHome = process.env.AWM_HOME;
+        process.env.AWM_HOME = fakeAwmHome;
+    });
+    afterEach(() => {
+        process.env.AWM_HOME = prevAwmHome;
+        if (dir)
+            fs_1.default.rmSync(dir, { recursive: true, force: true });
+        fs_1.default.rmSync(fakeAwmHome, { recursive: true, force: true });
+    });
+    const load = () => require('../../../src/commands/sensors/run');
+    const cmds = () => mockRunCommand.mock.calls.map(c => c[0]);
+    it('scopes a sensor that opted in and leaves one that did not at full scope', async () => {
+        // The core contract. tsc is whole-program: handed a subset it reports clean
+        // while the change breaks a caller it was never shown. Scoping is opt-in
+        // precisely so that sensor keeps measuring everything.
+        dir = project({ lint: LINT, typecheck: TYPECHECK });
+        mockChangedFiles.mockReturnValue({ files: ['src/a.ts'] });
+        await load().runSensors({ cwd: dir, changed: true });
+        expect(cmds()).toContain(`eslint --format json 'src/a.ts'`);
+        expect(cmds()).toContain('tsc --noEmit');
+    });
+    it('marks the scoped result so a scoped pass is not read as a full one', async () => {
+        dir = project({ lint: LINT, typecheck: TYPECHECK });
+        mockChangedFiles.mockReturnValue({ files: ['src/a.ts'] });
+        const out = await load().runSensors({ cwd: dir, changed: true });
+        expect(out.sensors.find((s) => s.name === 'lint').scope).toBe('changed');
+        expect(out.sensors.find((s) => s.name === 'typecheck').scope).toBeUndefined();
+        expect(out.changedScope).toEqual({ files: 1 });
+    });
+    it('falls back to the full command when the scope cannot be resolved', async () => {
+        // Not a git repo, git absent, bad ref. Running everything is slow; guessing at
+        // a narrower set would certify files nobody proved were the only ones touched.
+        dir = project({ lint: LINT });
+        mockChangedFiles.mockReturnValue({ files: [], error: 'not a git repository' });
+        const out = await load().runSensors({ cwd: dir, changed: true });
+        expect(cmds()).toContain('eslint --format json .');
+        expect(out.sensors[0].scope).toBeUndefined();
+        expect(out.changedScope).toEqual({ files: 0, error: 'not a git repository' });
+    });
+    it('skips an opted-in sensor when nothing changed, without touching the others', async () => {
+        dir = project({ lint: LINT, typecheck: TYPECHECK });
+        mockChangedFiles.mockReturnValue({ files: [] });
+        const out = await load().runSensors({ cwd: dir, changed: true });
+        const lint = out.sensors.find((s) => s.name === 'lint');
+        expect(lint.status).toBe('skipped');
+        expect(lint.skipReason).toBe('no changed files in scope');
+        expect(cmds()).toEqual(['tsc --noEmit']);
+    });
+    it('hands the sensor only the extensions it declared it can take', async () => {
+        // Without this, editing a README turns the lint gate red: eslint given a .md
+        // fails rather than skipping it.
+        dir = project({ lint: { ...LINT, changedExtensions: ['.ts', '.tsx'] } });
+        mockChangedFiles.mockReturnValue({ files: ['README.md', 'logo.png', 'src/a.ts'] });
+        await load().runSensors({ cwd: dir, changed: true });
+        expect(cmds()).toEqual([`eslint --format json 'src/a.ts'`]);
+    });
+    it('skips the sensor when the filter empties the scope, rather than running repo-wide', async () => {
+        // A docs-only commit means the lint sensor has nothing to say. Falling back to
+        // the full command here would reintroduce exactly the cost --changed removes.
+        dir = project({ lint: { ...LINT, changedExtensions: ['.ts'] }, typecheck: TYPECHECK });
+        mockChangedFiles.mockReturnValue({ files: ['README.md'] });
+        const out = await load().runSensors({ cwd: dir, changed: true });
+        expect(out.sensors.find((s) => s.name === 'lint').status).toBe('skipped');
+        expect(cmds()).toEqual(['tsc --noEmit']);
+    });
+    it('refuses a changedCmd without a {files} placeholder instead of running it repo-wide', async () => {
+        // Running the template as-is would cover the whole repo while the result
+        // claimed to be scoped. That is a mislabelled verdict, not a slow path.
+        dir = project({ lint: { ...LINT, changedCmd: 'eslint --format json .' } });
+        mockChangedFiles.mockReturnValue({ files: ['src/a.ts'] });
+        const out = await load().runSensors({ cwd: dir, changed: true });
+        expect(out.sensors[0].status).toBe('inconclusive');
+        expect(out.overall).toBe('not_certified');
+        expect(mockRunCommand).not.toHaveBeenCalled();
+    });
+    it('refuses to combine --changed with a baseline capture', async () => {
+        // buildBaseline snapshots the run it is given, so baselining a scoped run
+        // would write a baseline covering only the diff and silently drop every
+        // accepted finding elsewhere — which then reports as NEW on the next full run.
+        dir = project({ lint: LINT });
+        mockChangedFiles.mockReturnValue({ files: ['src/a.ts'] });
+        await expect(load().runSensors({ cwd: dir, changed: true, ignoreBaseline: true }))
+            .rejects.toThrow(/cannot define the accepted set/);
+    });
+    it('runs everything at full scope when --changed is absent', async () => {
+        dir = project({ lint: LINT, typecheck: TYPECHECK });
+        const out = await load().runSensors({ cwd: dir });
+        expect(cmds()).toEqual(['eslint --format json .', 'tsc --noEmit']);
+        expect(mockChangedFiles).not.toHaveBeenCalled();
+        expect(out.changedScope).toBeUndefined();
+    });
+    it('passes the requested base through to the scope resolver', async () => {
+        dir = project({ lint: LINT });
+        mockChangedFiles.mockReturnValue({ files: ['src/a.ts'] });
+        await load().runSensors({ cwd: dir, changed: true, base: 'main' });
+        expect(mockChangedFiles).toHaveBeenCalledWith(dir, 'main');
+    });
+});

package/package.json

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