agentic-workflow-manager 9.18.0 → 9.20.0

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

@@ -0,0 +1,492 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runChangeNew = runChangeNew;
+exports.runChangeValidate = runChangeValidate;
+exports.registerChangeCommand = registerChangeCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const command_1 = require("../../core/changes/command");
+const store_1 = require("../../core/journal/store");
+const store_2 = require("../../core/ledger/store");
+const parse_1 = require("../../core/changes/parse");
+const git_1 = require("../../core/changes/git");
+const range_1 = require("../../core/changes/range");
+const derive_1 = require("../../core/changes/derive");
+const trailers_1 = require("../../core/changes/trailers");
+const receipt_1 = require("../../core/changes/receipt");
+const render_1 = require("../../core/changes/render");
+const fs_safe_1 = require("../../core/changes/fs-safe");
+const record_io_1 = require("../../core/changes/record-io");
+const text_safety_1 = require("../../core/changes/text-safety");
+const types_1 = require("../../core/changes/types");
+const validate_shape_1 = require("../../core/changes/validate-shape");
+const REMEDY_RECEIPT = 'commit your work, then run awm sensors run';
+const REMEDY_SPLIT = 'split the change into smaller ones';
+const REMEDY_SENSORS = 'reduce the sensors listed in .awm/sensors.json (the sensor receipt makes the record too large)';
+/** R3.4: the remedy that names the cause of an oversized record: the sensor receipt when it outweighs the module list, else the change itself. */
+function tooLargeRemedy(fields, verification) {
+    const bytes = (value) => Buffer.byteLength(JSON.stringify(value), 'utf8');
+    return bytes(verification.sensors) > bytes(fields.modules) ? REMEDY_SENSORS : REMEDY_SPLIT;
+}
+const MAX_PROVENANCE_VALUE = 200;
+const MAX_ISSUE_URL = 2048;
+const CREATION_ONLY_FLAGS = ['plan', 'issue', 'model', 'session'];
+// ---- Flags (R3.11b, R3.12) ----
+/** Provenance text: one line, not blank, at most 200 code points, writable as UTF-8. */
+function isProvenanceValue(v) {
+    return (0, text_safety_1.isSingleLine)(v) && v.trim() !== '' && [...v].length <= MAX_PROVENANCE_VALUE && (0, text_safety_1.isWellFormed)(v);
+}
+/** A static description of the first bad flag (never the value), or null. */
+function flagProblem(opts, root) {
+    for (const key of ['base', 'plan', 'issue', 'model', 'session']) {
+        if (opts[key] !== undefined && typeof opts[key] !== 'string')
+            return `--${key} must be a string`;
+    }
+    if (opts.refresh !== undefined && typeof opts.refresh !== 'boolean')
+        return '--refresh must be a boolean flag';
+    if (opts.refresh === true) {
+        const clash = CREATION_ONLY_FLAGS.find((key) => opts[key] !== undefined);
+        if (clash)
+            return `--refresh cannot be combined with --${clash}: it only applies when a record is created`;
+    }
+    for (const key of ['model', 'session']) {
+        const v = opts[key];
+        if (v !== undefined && !isProvenanceValue(v))
+            return `--${key} must be one non-blank line of at most ${MAX_PROVENANCE_VALUE} characters`;
+    }
+    if (opts.issue !== undefined && !((0, text_safety_1.isWellFormed)(opts.issue) && (0, text_safety_1.isHttpsUrl)(opts.issue, { allowCredentials: false, maxLength: MAX_ISSUE_URL })))
+        return '--issue must be an https URL without credentials';
+    if (opts.plan !== undefined && !(0, fs_safe_1.isRegularFileInside)(root, opts.plan))
+        return '--plan must be an existing regular file inside the repository';
+    return null;
+}
+// ---- Provenance (R3.8) ----
+/** Only keys with a source: the journal (when present and readable) and the flags. Never throws; a bad journal contributes nothing. */
+function provenance(root, opts) {
+    const out = {};
+    try {
+        const state = (0, store_1.readJournal)(root, (0, store_2.detectBranch)(root)).state;
+        const agent = state?.admissionContext?.provider;
+        if (typeof agent === 'string' && isProvenanceValue(agent))
+            out.agent = agent;
+        if ((0, text_safety_1.isCanonicalIso)(state?.cycle?.startedAt))
+            out.started_at = state.cycle.startedAt;
+        if ((0, text_safety_1.isCanonicalIso)(state?.cycle?.completedAt))
+            out.finished_at = state.cycle.completedAt;
+    }
+    catch {
+        // A damaged or unreadable journal is not an error of this command.
+    }
+    if (opts.model !== undefined)
+        out.model = opts.model;
+    if (opts.session !== undefined)
+        out.session = opts.session;
+    return out;
+}
+// ---- awm change new ----
+function utcDate(deps) {
+    try {
+        const moment = (deps.now ?? (() => new Date()))();
+        if (!(moment instanceof Date) || Number.isNaN(moment.getTime()))
+            return null;
+        const iso = moment.toISOString();
+        return /^\d{4}-\d{2}-\d{2}T/.test(iso) ? iso.slice(0, 10) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function changeNew(cwd, slug, rawOpts, deps) {
+    if (typeof cwd !== 'string' || cwd.length === 0)
+        return (0, command_1.fail)('invalid-input', 'the working directory must be a non-empty string');
+    if (!(0, parse_1.isValidSlug)(slug))
+        return (0, command_1.fail)('slug-invalid', `slug "${(0, text_safety_1.esc)(slug)}" must match [a-z0-9]+(-[a-z0-9]+)* and be at most 64 characters`);
+    if (rawOpts !== undefined && !(0, text_safety_1.isObj)(rawOpts))
+        return (0, command_1.fail)('flag-invalid', 'options must be an object');
+    const opts = (rawOpts ?? {});
+    const root = (0, git_1.repoRoot)(cwd);
+    if (root === null)
+        return (0, command_1.fail)('not-a-git-repo', 'awm change must run inside a git repository');
+    const flag = flagProblem(opts, root);
+    if (flag)
+        return (0, command_1.fail)('flag-invalid', flag);
+    // Pin HEAD before anything is derived: the fields, the dirty check and the receipt all describe this one commit.
+    const range = (0, range_1.resolveRange)(root, opts.base);
+    if (!range.ok)
+        return (0, command_1.failed)(range.failure);
+    const { head } = range;
+    const derived = (0, derive_1.deriveFields)(root, range.mergeBase);
+    if (!derived.ok)
+        return (0, command_1.fail)(derived.diagnostic.code, derived.diagnostic.message);
+    const movedAfterDerive = (0, range_1.headMovedFailure)(root, head);
+    if (movedAfterDerive)
+        return (0, command_1.failed)(movedAfterDerive);
+    // R3.6: the tree equals HEAD (apart from docs/changes and the runtime state) and a receipt vouches for HEAD.
+    if ((0, git_1.isDirtyOutside)(root, [types_1.RECORD_DIR]))
+        return (0, command_1.fail)('tree-dirty', `working tree has uncommitted changes outside ${types_1.RECORD_DIR}/`, REMEDY_RECEIPT);
+    const receipt = (0, receipt_1.readReceipt)(root, head);
+    if (!receipt.ok)
+        return (0, command_1.fail)(receipt.code, `no valid sensor receipt for HEAD ${head.slice(0, 12)}`, REMEDY_RECEIPT);
+    const verification = { commit: receipt.receipt.commit, overall: receipt.receipt.overall, sensors: receipt.receipt.sensors, receipt_digest: receipt.receipt.digest };
+    let dir = (0, record_io_1.inspectRecordDir)(root);
+    const dirProblem = (0, range_1.recordDirProblem)(dir, 'write');
+    if (dirProblem)
+        return (0, command_1.failed)(dirProblem);
+    const existing = dir.kind === 'ok' ? (0, record_io_1.recordsWithSlug)(dir.dir, slug) : [];
+    if (existing === null)
+        return (0, command_1.fail)('io-failed', `could not list ${types_1.RECORD_DIR}`);
+    if (opts.refresh === true)
+        return refresh({ dir, existing, slug, fields: derived.fields, verification, head, root });
+    if (existing.length > 0)
+        return (0, command_1.fail)('record-exists', `a record for slug "${slug}" already exists (${existing[0]})`, 'use --refresh to update derived fields');
+    const date = utcDate(deps);
+    const id = date === null ? null : `${date}-${slug}`;
+    if (id === null || !(0, parse_1.isValidRecordFileName)(`${id}.md`))
+        return (0, command_1.fail)('date-invalid', 'the clock did not yield a valid calendar date');
+    const links = {};
+    if (opts.plan !== undefined)
+        links.plan = opts.plan;
+    if (opts.issue !== undefined)
+        links.issue = opts.issue;
+    const content = (0, render_1.renderSkeleton)({ id, fields: derived.fields, verification, links, provenance: provenance(root, opts) });
+    if (content === null)
+        return (0, command_1.fail)('skeleton-invalid', 'the record skeleton could not be rendered');
+    // R3.4: a change touching thousands of directories (or a huge receipt) outgrows the record bound: say so, instead of a validation code.
+    if (Buffer.byteLength(content, 'utf8') > types_1.MAX_RECORD_BYTES)
+        return (0, command_1.fail)('record-too-large', `the generated record would exceed ${types_1.MAX_RECORD_BYTES} bytes`, tooLargeRemedy(derived.fields, verification));
+    // Backstop: the only thing wrong with a skeleton may be its pending markers.
+    const problem = (0, validate_shape_1.validateRecordShape)(`${id}.md`, content, { root }).diagnostics.find((d) => d.code !== 'pending-content');
+    if (problem)
+        return (0, command_1.fail)('skeleton-invalid', `the generated record failed validation: ${(0, text_safety_1.esc)(problem.code)}${problem.field ? ` (${(0, text_safety_1.esc)(problem.field)})` : ''}`);
+    const movedBeforeWrite = (0, range_1.headMovedFailure)(root, head);
+    if (movedBeforeWrite)
+        return (0, command_1.failed)(movedBeforeWrite);
+    if (dir.kind === 'absent')
+        dir = (0, record_io_1.createRecordDir)(root);
+    if (dir.kind !== 'ok')
+        return (0, command_1.failed)((0, range_1.recordDirProblem)(dir, 'create'));
+    const written = (0, record_io_1.createExclusive)(path_1.default.join(dir.dir, `${id}.md`), content);
+    if (written === 'exists')
+        return (0, command_1.fail)('record-exists', `${id}.md already exists`, 'use --refresh to update derived fields');
+    if (written === 'error')
+        return (0, command_1.fail)('io-failed', `could not write ${types_1.RECORD_DIR}/${id}.md`);
+    return { code: 0, stdout: `Created ${types_1.RECORD_DIR}/${id}.md\n`, stderr: '' };
+}
+/** R3.11: rewrites only the derived fields and verification of the one existing record. */
+function refresh({ dir, existing, slug, fields, verification, head, root }) {
+    if (dir.kind !== 'ok' || existing.length === 0)
+        return (0, command_1.fail)('record-missing', `no record found for slug "${slug}"`, `run awm change new ${slug} to create it`);
+    if (existing.length > 1)
+        return (0, command_1.fail)('record-ambiguous', `${existing.length} records exist for slug "${slug}"; keep one`);
+    const name = existing[0];
+    const target = path_1.default.join(dir.dir, name);
+    const current = (0, record_io_1.readRecord)(target, name);
+    if (!current.ok)
+        return (0, command_1.fail)(current.code, current.message);
+    const next = (0, render_1.refreshDerived)(current.text, fields, verification);
+    if (next !== null && Buffer.byteLength(next, 'utf8') > types_1.MAX_RECORD_BYTES)
+        return (0, command_1.fail)('record-too-large', `${(0, text_safety_1.esc)(name)} would exceed ${types_1.MAX_RECORD_BYTES} bytes once refreshed`, tooLargeRemedy(fields, verification));
+    if (next === null)
+        return (0, command_1.fail)('record-invalid', `${(0, text_safety_1.esc)(name)} has unparseable frontmatter, misses a derived key, or cannot be refreshed safely`);
+    const moved = (0, range_1.headMovedFailure)(root, head);
+    if (moved)
+        return (0, command_1.failed)(moved);
+    // Someone else may have edited (or replaced) the record since it was read: their version wins, nothing is written.
+    if (!(0, record_io_1.unchangedSince)(target, current.snapshot))
+        return (0, command_1.fail)('record-changed', `${(0, text_safety_1.esc)(name)} changed while it was being refreshed; run the command again`);
+    const written = (0, record_io_1.replaceRecord)(target, next);
+    if (!written.ok)
+        return (0, command_1.fail)('io-failed', `could not write ${(0, text_safety_1.esc)(name)} (${(0, text_safety_1.esc)(written.code)})`);
+    return { code: 0, stdout: `Refreshed ${types_1.RECORD_DIR}/${name}\n`, stderr: '' };
+}
+/** Never throws: any unexpected failure becomes a diagnostic. */
+function runChangeNew(cwd, slug, opts, deps = {}) {
+    try {
+        return changeNew(cwd, slug, opts, (0, text_safety_1.isObj)(deps) ? deps : {});
+    }
+    catch (error) {
+        return (0, command_1.fail)('internal-error', `unexpected failure (${(0, text_safety_1.esc)(error instanceof Error ? error.name : 'unknown')})`);
+    }
+}
+/** R4.5: diagnostics per record. When more were found the last slot becomes a `diagnostics-truncated` marker. */
+const MAX_RECORD_DIAGNOSTICS = 20;
+/** Records validated per run; further ones are not read and make the run invalid (`too-many-records`). */
+const MAX_RECORDS = 50;
+/** Paths listed in a `code-changed-after-verification` message (the message itself is clipped to one line of 300 units). */
+const MAX_LATE_PATHS = 20;
+/** Each half of a `derived-mismatch` message gets this many UTF-16 units, so the recorded and the derived value are both always visible. */
+const MAX_SHOWN_VALUE = 120;
+const safeDiagnostic = (d) => {
+    const base = { code: (0, command_1.line)(d.code), message: (0, command_1.line)(d.message) };
+    return d.field === undefined ? base : { ...base, field: (0, command_1.line)(d.field) };
+};
+/**
+ * One record's report: every text field made single-line and bounded, at most 20 diagnostics. `dropped` counts the diagnostics
+ * the shape validator's own cap already removed, so the truncation marker counts every omitted diagnostic.
+ */
+function finish(recordPath, list, dropped = 0) {
+    const all = list.map(safeDiagnostic);
+    const total = all.length + dropped;
+    const kept = total > MAX_RECORD_DIAGNOSTICS
+        ? [...all.slice(0, MAX_RECORD_DIAGNOSTICS - 1), { code: 'diagnostics-truncated', message: `${total - (MAX_RECORD_DIAGNOSTICS - 1)} more diagnostics omitted` }]
+        : all;
+    return { path: (0, command_1.line)(recordPath), state: kept.length === 0 ? 'valid' : 'invalid', diagnostics: kept };
+}
+function formatText(state, records) {
+    const lines = [`Change Record validation: ${state}${state === 'exempt' ? ' (Change-Record: none)' : ''}`];
+    for (const r of records) {
+        lines.push((0, command_1.line)(`- ${r.path}: ${r.state}`));
+        for (const d of r.diagnostics)
+            lines.push((0, command_1.line)(`  - ${d.code}${d.field === undefined ? '' : ` (${d.field})`}: ${d.message}`));
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** R4.5: the one place a verdict becomes output: a text report or one JSON line, exit 0 unless invalid. */
+function render(json, state, records) {
+    return { code: state === 'invalid' ? 2 : 0, stdout: json ? `${JSON.stringify({ state, records })}\n` : formatText(state, records), stderr: '' };
+}
+/** R4.5: an operational failure. With --json it is the one-line report shape (state invalid, record `docs/changes`), else the stderr form of `change new`. */
+function failure(json, code, message, remedy) {
+    if (!json)
+        return (0, command_1.fail)(code, message, remedy);
+    return render(true, 'invalid', [finish(types_1.RECORD_DIR, [{ code, message: remedy ? `${message}; ${remedy}` : message }])]);
+}
+const deriveOnce = (run) => (run.derived ??= (0, derive_1.deriveFields)(run.root, run.mergeBaseSha));
+function lateFiles(run, commit) {
+    if (!run.late.has(commit)) {
+        const files = (0, git_1.changedFiles)(run.root, commit, run.head)?.filter((f) => !f.startsWith(`${types_1.RECORD_DIR}/`));
+        run.late.set(commit, files === undefined ? null : { count: files.length, first: files.slice(0, MAX_LATE_PATHS) });
+    }
+    return run.late.get(commit) ?? null;
+}
+/** A git failure counts as "not an ancestor": the caller reports `verification-commit-foreign` (fail closed). */
+function isAncestorOfHead(run, commit) {
+    if (!run.ancestors.has(commit))
+        run.ancestors.set(commit, (0, git_1.isAncestor)(run.root, commit, run.head));
+    return run.ancestors.get(commit) === true;
+}
+/** The same sensors with the same statuses, compared as name-sorted pairs (never by JavaScript object key order). */
+const sameSensors = (a, b) => JSON.stringify((0, receipt_1.sensorPairs)(a)) === JSON.stringify((0, receipt_1.sensorPairs)(b));
+/** A derived value for a message: strings escaped inside quotes (esc), lists bracketed, everything else as JSON; at most MAX_SHOWN_VALUE units. */
+function show(value) {
+    const text = showAll(value);
+    return text.length > MAX_SHOWN_VALUE ? `${(0, text_safety_1.sliceNoSplit)(text, MAX_SHOWN_VALUE - 1)}…` : text;
+}
+function showAll(value) {
+    if (typeof value === 'string')
+        return `"${(0, text_safety_1.esc)(value)}"`;
+    if (Array.isArray(value))
+        return `[${value.map(showAll).join(', ')}]`;
+    return JSON.stringify(value) ?? 'undefined';
+}
+/** R4.3: the recomputed derived fields equal the record's, one diagnostic per differing field. */
+function checkDerived(run, record, out) {
+    const derived = deriveOnce(run);
+    if (!derived.ok) {
+        out.push(derived.diagnostic);
+        return;
+    }
+    for (const key of types_1.DERIVED_KEYS) {
+        if (JSON.stringify(record[key]) !== JSON.stringify(derived.fields[key])) {
+            out.push({ code: 'derived-mismatch', field: key, message: `${key} is ${show(record[key])} but git derives ${show(derived.fields[key])}` });
+        }
+    }
+}
+/** R4.3: the verified commit is HEAD or an ancestor of it, and nothing outside docs/changes/ changed since. */
+function checkVerifiedCommit(run, commit, out) {
+    if (!isAncestorOfHead(run, commit)) {
+        out.push({ code: 'verification-commit-foreign', field: 'verification.commit', message: `${commit.slice(0, 12)} is not HEAD or an ancestor of HEAD` });
+        return;
+    }
+    const late = lateFiles(run, commit);
+    if (late === null) {
+        out.push({ code: 'git-failed', message: `git could not list the files changed since ${commit.slice(0, 12)}` });
+        return;
+    }
+    if (late.count === 0)
+        return;
+    out.push({ code: 'code-changed-after-verification', message: `${late.count} file${late.count === 1 ? '' : 's'} changed after ${commit.slice(0, 12)}: ${late.first.map(text_safety_1.esc).join(', ')}${late.count > MAX_LATE_PATHS ? ', …' : ''}` });
+}
+/** R4.4: the receipt of the verified commit exists, matches the record's verification block, and says pass. */
+function checkReceipt(run, record, out) {
+    const { verification } = record;
+    const receipt = (0, receipt_1.readReceipt)(run.root, verification.commit);
+    if (!receipt.ok) {
+        out.push({ code: receipt.code, field: 'verification.commit', message: `no valid sensor receipt for ${verification.commit.slice(0, 12)}` });
+        return;
+    }
+    const r = receipt.receipt;
+    if (r.digest !== verification.receipt_digest)
+        out.push({ code: 'verification-mismatch', field: 'verification.receipt_digest', message: 'receipt_digest differs from the sensor receipt' });
+    if (r.overall !== verification.overall)
+        out.push({ code: 'verification-mismatch', field: 'verification.overall', message: `the record says ${(0, text_safety_1.esc)(verification.overall)} but the sensor receipt says ${(0, text_safety_1.esc)(r.overall)}` });
+    if (!sameSensors(r.sensors, verification.sensors))
+        out.push({ code: 'verification-mismatch', field: 'verification.sensors', message: 'the sensors differ from the sensor receipt' });
+    if (r.overall !== 'pass')
+        out.push({ code: 'verification-not-passing', field: 'verification.overall', message: `the sensor verdict is ${(0, text_safety_1.esc)(r.overall)}, not pass` });
+}
+/** R4.3: without a path the verdict describes the committed record. Git unable to tell fails closed. */
+function checkCommitted(root, rel, out) {
+    const clean = (0, git_1.isCommittedClean)(root, rel);
+    if (clean === true)
+        return;
+    out.push({ code: 'record-uncommitted', message: clean === false ? `${(0, text_safety_1.esc)(rel)} has uncommitted changes; commit it and validate again` : `could not tell whether ${(0, text_safety_1.esc)(rel)} has uncommitted changes` });
+}
+/** The records are read from the working tree, through the symlink-safe, size-bounded readers. Never throws. */
+function validateOne(run, rel, requireCommitted) {
+    const name = path_1.default.posix.basename(rel);
+    /** A record that cannot even be read: one diagnostic. */
+    const single = (code, message) => finish(rel, [{ code, message }]);
+    const { dir } = run;
+    if (dir.kind !== 'ok') {
+        const dirProblem = (0, range_1.recordDirProblem)(dir, 'read');
+        return dirProblem ? single(dirProblem.code, dirProblem.message) : single('record-missing', `${types_1.RECORD_DIR}/ does not exist`);
+    }
+    if (!(0, fs_safe_1.isRegularFileInside)(run.root, rel))
+        return single('record-missing', `${(0, text_safety_1.esc)(rel)} is not a regular file in the working tree`);
+    const read = (0, record_io_1.readRecord)(path_1.default.join(dir.dir, name), name);
+    if (!read.ok)
+        return single(read.tooLarge === true ? 'record-too-large' : read.code, read.message);
+    const diagnostics = [];
+    if (requireCommitted)
+        checkCommitted(run.root, rel, diagnostics);
+    const shape = (0, validate_shape_1.validateRecordShape)(name, read.text, { root: run.root });
+    // The shape validator's own cap ends its list with a marker; finish() writes one marker for the whole record instead.
+    const dropped = shape.omitted ?? 0;
+    diagnostics.push(...(dropped > 0 ? shape.diagnostics.slice(0, -1) : shape.diagnostics));
+    const record = shape.record;
+    if (record) {
+        checkDerived(run, record, diagnostics);
+        checkVerifiedCommit(run, record.verification.commit, diagnostics);
+        if (run.strict)
+            checkReceipt(run, record, diagnostics);
+    }
+    return finish(rel, diagnostics, dropped);
+}
+/** The repo-relative, `/`-separated path `target` (read from `cwd`) names, or null when it lies outside the repository. */
+function repoRelative(root, cwd, target) {
+    if (target === '' || target.includes('\0'))
+        return null;
+    const real = (p) => { try {
+        return fs_1.default.realpathSync.native(p);
+    }
+    catch {
+        return p;
+    } };
+    for (const from of new Set([cwd, real(cwd)])) {
+        const resolved = path_1.default.resolve(from, target);
+        for (const full of new Set([resolved, real(resolved)])) {
+            for (const base of new Set([root, real(root)])) {
+                const rel = path_1.default.relative(base, full);
+                if (rel !== '' && rel !== '..' && !rel.startsWith(`..${path_1.default.sep}`) && !path_1.default.isAbsolute(rel))
+                    return rel.split(path_1.default.sep).join('/');
+            }
+        }
+    }
+    return null;
+}
+/** True only for a real `--json` flag; anything else (including a malformed options value) keeps the stderr form. */
+function wantsJson(rawOpts) {
+    try {
+        return (0, text_safety_1.isObj)(rawOpts) && rawOpts.json === true;
+    }
+    catch {
+        return false;
+    }
+}
+function validateOpts(rawOpts) {
+    if (rawOpts !== undefined && !(0, text_safety_1.isObj)(rawOpts))
+        return 'options must be an object';
+    const opts = (rawOpts ?? {});
+    if (opts.base !== undefined && typeof opts.base !== 'string')
+        return '--base must be a string';
+    for (const key of ['strict', 'json'])
+        if (opts[key] !== undefined && typeof opts[key] !== 'boolean')
+            return `--${key} must be a boolean flag`;
+    return opts;
+}
+const verdict = (records) => ({ state: records.every((r) => r.state === 'valid') ? 'valid' : 'invalid', records });
+/** The records added in the range, validated; the opt-out trailer exempts a branch that adds none. Null when git cannot list them. */
+function branchVerdict(run) {
+    const added = (0, git_1.addedFilesUnder)(run.root, run.mergeBaseSha, run.head, types_1.RECORD_DIR);
+    if (added === null)
+        return null;
+    const names = added.filter(parse_1.isRecordPath);
+    if (names.length === 0) {
+        if ((0, trailers_1.hasOptOut)(run.root, [`${run.mergeBaseSha}..${run.head}`]))
+            return { state: 'exempt', records: [] };
+        return verdict([finish(types_1.RECORD_DIR, [{ code: 'record-missing', message: 'this branch adds no Change Record and no commit carries Change-Record: none' }])]);
+    }
+    const records = names.slice(0, MAX_RECORDS).map((name) => validateOne(run, name, true));
+    if (names.length > MAX_RECORDS)
+        records.push(finish(types_1.RECORD_DIR, [{ code: 'too-many-records', message: `${names.length} records were added; only the first ${MAX_RECORDS} were validated` }]));
+    return verdict(records);
+}
+function changeValidate(cwd, target, rawOpts) {
+    const json = wantsJson(rawOpts);
+    const bail = (code, message, remedy) => failure(json, code, message, remedy);
+    if (typeof cwd !== 'string' || cwd.length === 0)
+        return bail('invalid-input', 'the working directory must be a non-empty string');
+    if (target !== undefined && typeof target !== 'string')
+        return bail('path-invalid', 'the path must be a string');
+    const opts = validateOpts(rawOpts);
+    if (typeof opts === 'string')
+        return bail('flag-invalid', opts);
+    const root = (0, git_1.repoRoot)(cwd);
+    if (root === null)
+        return bail('not-a-git-repo', 'awm change must run inside a git repository');
+    let rel = null;
+    if (target !== undefined) {
+        rel = repoRelative(root, cwd, target);
+        if (rel === null || !(0, parse_1.isRecordPath)(rel))
+            return bail('path-invalid', `"${(0, text_safety_1.esc)(target)}" must name a file ${types_1.RECORD_DIR}/YYYY-MM-DD-<slug>.md of this repository`);
+    }
+    // Pin HEAD: the range, the ancestry and the late-file checks all describe this one commit.
+    const range = (0, range_1.resolveRange)(root, opts.base);
+    if (!range.ok)
+        return bail(range.failure.code, range.failure.message, range.failure.remedy);
+    const run = { root, head: range.head, mergeBaseSha: range.mergeBase, strict: opts.strict === true, dir: (0, record_io_1.inspectRecordDir)(root), ancestors: new Map(), late: new Map() };
+    const outcome = rel !== null ? verdict([validateOne(run, rel, false)]) : branchVerdict(run);
+    if (outcome === null)
+        return bail('git-failed', `git could not list the records added since ${range.mergeBase.slice(0, 12)}`);
+    const moved = (0, range_1.headMovedFailure)(root, range.head);
+    if (moved)
+        return bail(moved.code, moved.message);
+    return render(json, outcome.state, outcome.records);
+}
+/** Never throws: any unexpected failure becomes a diagnostic. Read-only (R4.6): nothing here writes a file. */
+function runChangeValidate(cwd, target, opts) {
+    try {
+        return changeValidate(cwd, target, opts);
+    }
+    catch (error) {
+        return failure(wantsJson(opts), 'internal-error', `unexpected failure (${(0, text_safety_1.esc)(error instanceof Error ? error.name : 'unknown')})`);
+    }
+}
+/** The action wrapper: the working directory may be gone, and nothing may throw out of the action. */
+function inCwd(command, json = false) {
+    (0, command_1.inCwd)(command, () => failure(json, 'not-a-git-repo', 'the working directory is not accessible'));
+}
+function registerChangeCommand(program, deps = {}) {
+    const change = program.command('change').description('create and validate the Change Record of the current branch');
+    change
+        .command('new <slug>')
+        .description('create docs/changes/YYYY-MM-DD-<slug>.md with derived fields and pending narrative')
+        .option('--base <ref>', 'base branch (default: origin/HEAD, main, master)')
+        .option('--plan <path>', 'repo-relative plan file to link')
+        .option('--issue <url>', 'https issue URL to link')
+        .option('--model <model>', 'provenance: model identifier')
+        .option('--session <session>', 'provenance: session id or URL (avoid internal URLs in public repos)')
+        .option('--refresh', 'recompute only derived fields and verification of the existing record')
+        .action((slug, opts) => inCwd((cwd) => runChangeNew(cwd, slug, opts, deps)));
+    change
+        .command('validate [path]')
+        .description('validate the Change Record(s) added by this branch, or one record (--strict also checks the sensor receipt)')
+        .option('--base <ref>', 'base branch (default: origin/HEAD, main, master)')
+        .option('--strict', 'require a matching, passing sensor receipt for verification.commit')
+        .option('--json', 'print a single JSON line')
+        .action((target, opts) => inCwd((cwd) => runChangeValidate(cwd, target, opts), wantsJson(opts)));
+}

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

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runChangesList = runChangesList;
+exports.registerChangesCommand = registerChangesCommand;
+const path_1 = __importDefault(require("path"));
+const command_1 = require("../../core/changes/command");
+const git_1 = require("../../core/changes/git");
+const list_1 = require("../../core/changes/list");
+const list_parse_1 = require("../../core/changes/list-parse");
+const render_list_1 = require("../../core/changes/render-list");
+const text_safety_1 = require("../../core/changes/text-safety");
+const FORMATS = ['text', 'json', 'voice'];
+const DEFAULT_SINCE = '24h';
+/** A static description of the first flag of the wrong type, or null. */
+function flagProblem(opts) {
+    for (const key of ['since', 'base', 'format'])
+        if (opts[key] !== undefined && typeof opts[key] !== 'string')
+            return `--${key} must be a string`;
+    return null;
+}
+/** The clock's instant, or null when the clock throws or does not yield a valid date. */
+function clock(deps) {
+    try {
+        const moment = (deps.now ?? (() => new Date()))();
+        return moment instanceof Date && !Number.isNaN(moment.getTime()) ? moment : null;
+    }
+    catch {
+        return null;
+    }
+}
+function changesList(cwd, rawOpts, rawDeps) {
+    if (typeof cwd !== 'string' || cwd.length === 0)
+        return (0, command_1.fail)('invalid-input', 'the working directory must be a non-empty string');
+    if (rawOpts !== undefined && !(0, text_safety_1.isObj)(rawOpts))
+        return (0, command_1.fail)('flag-invalid', 'options must be an object');
+    if (rawDeps !== undefined && !(0, text_safety_1.isObj)(rawDeps))
+        return (0, command_1.fail)('invalid-input', 'dependencies must be an object');
+    const opts = (rawOpts ?? {});
+    const deps = (rawDeps ?? {});
+    const flag = flagProblem(opts);
+    if (flag)
+        return (0, command_1.fail)('flag-invalid', flag);
+    const format = opts.format ?? 'text';
+    if (!FORMATS.includes(format))
+        return (0, command_1.fail)('format-invalid', `--format "${(0, text_safety_1.esc)(format)}" must be text, json or voice`);
+    const moment = clock(deps);
+    if (moment === null)
+        return (0, command_1.fail)('invalid-input', 'the clock did not yield a valid date');
+    const window = opts.since ?? DEFAULT_SINCE;
+    const since = (0, list_parse_1.parseSince)(window, moment);
+    if (since === null)
+        return (0, command_1.fail)('since-invalid', `--since "${(0, text_safety_1.esc)(window)}" must be <n>h, <n>d or YYYY-MM-DD`);
+    const root = (0, git_1.repoRoot)(cwd);
+    if (root === null)
+        return (0, command_1.fail)('not-a-git-repo', 'awm changes must run inside a git repository');
+    const outcome = (0, list_1.listChanges)(root, { base: opts.base, since, limit: deps.limit });
+    if (!outcome.ok)
+        return (0, command_1.failed)(outcome.failure);
+    const fallback = path_1.default.basename(root);
+    const stdout = format === 'json' ? (0, render_list_1.renderJson)(outcome.result) : format === 'voice' ? (0, render_list_1.renderVoice)(outcome.result, fallback) : (0, render_list_1.renderText)(outcome.result, fallback);
+    return { code: 0, stdout, stderr: '' };
+}
+/** `awm changes list`: read-only; never throws (any unexpected failure becomes an `internal-error` on stderr). */
+function runChangesList(cwd, opts, deps = {}) {
+    try {
+        return changesList(cwd, opts, deps);
+    }
+    catch (error) {
+        return (0, command_1.fail)('internal-error', `unexpected failure (${(0, text_safety_1.esc)(error instanceof Error ? error.name : 'unknown')})`);
+    }
+}
+function registerChangesCommand(program, deps = {}) {
+    const changes = program.command('changes').description('query the Change Records merged into the base branch');
+    changes
+        .command('list')
+        .description('list the changes of the base branch with their Change Record and derived merge/release state')
+        .option('--since <window>', '<n>h, <n>d or YYYY-MM-DD (default 24h)')
+        .option('--base <ref>', 'base branch (default: origin/HEAD, main, master)')
+        .option('--format <format>', 'text | json | voice (default text)')
+        .action((opts) => (0, command_1.inCwd)((cwd) => runChangesList(cwd, opts, deps), () => (0, command_1.fail)('not-a-git-repo', 'the working directory is not accessible')));
+}

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

@@ -283,7 +283,7 @@ function registerPlanCommand(program, deps = { validatePlanFile: validate_1.vali
         .requiredOption('--cwd <path>', 'repository root for plan containment and source resolution')
         .option('--execution-mode <mode>', 'explicit override: interactivo or desatendido')
         .option('--require-current', 'require authoritative consumed-contract currentness')
-        .option('--verify-sensors', 'require an empirical sensor pass')
+        .option('--verify-sensors', 'require an empirical sensor pass; read-only observation skips git-ignored build output (see .awm/admission.json)')
         .option('--runtime-kind <kind>', 'routing runtime kind for compact v2')
         .option('--runtime-version <version>', 'routing runtime version for compact v2')
         .option('--account-scope-digest <sha>', 'routing account scope digest for compact v2')

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

@@ -17,6 +17,7 @@ const registries_1 = require("../../core/registries");
 const verdict_1 = require("./verdict");
 const bootstrap_1 = require("./bootstrap");
 const unresolved_1 = require("./unresolved");
+const receipt_1 = require("../../core/changes/receipt");
 /** Commander coercion for coverage recurrence emphasis. It deliberately runs
  * before the action, so an invalid value cannot trigger ledger I/O. */
 function parsePositiveSafeInteger(value) {
@@ -53,6 +54,8 @@ function registerSensorsCommand(program) {
         .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) => {
+        // R2.2b: the receipt belongs to the manifest that runs (the one `runSensors` resolves from this cwd), not to the cwd.
+        const pre = (0, receipt_1.isFullSelection)(opts) ? (0, receipt_1.captureReceiptPrecondition)((0, run_1.findManifestDir)(process.cwd()) ?? process.cwd()) : null;
         const output = await (0, run_1.runSensors)({
             fast: opts.fast, slow: opts.slow, all: opts.all,
             changed: opts.changed, base: opts.base,
@@ -60,6 +63,12 @@ function registerSensorsCommand(program) {
         // 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');
+        // R2: the receipt is a side effect; it never changes stdout or the exit code.
+        if (pre) {
+            const note = (0, receipt_1.finalizeRunReceipt)(pre, output);
+            if (note)
+                process.stderr.write(note);
+        }
         process.exitCode = (0, verdict_1.exitCodeForVerdict)(output.overall);
     });
     sensors