@holdyourvoice/hyv 3.1.1 → 3.3.0

package/dist/canonical-json.js

@@ -0,0 +1,123 @@
+const MAX_DEPTH = 64;
+const MAX_NODES = 10_000;
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+}
+function validUnicode(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return false;
+            index += 1;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff)
+            return false;
+    }
+    return true;
+}
+function serialize(value, depth, budget) {
+    budget.nodes += 1;
+    if (depth > MAX_DEPTH || budget.nodes > MAX_NODES)
+        throw new Error('Value is not valid canonical JSON: complexity limit exceeded.');
+    if (value === null || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (typeof value === 'string') {
+        if (!validUnicode(value))
+            throw new Error('Value is not valid canonical JSON: lone surrogate.');
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value)) || Object.is(value, -0))
+            throw new Error('Value is not valid canonical JSON: unsafe number.');
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map((item) => serialize(item, depth + 1, budget)).join(',')}]`;
+    if (isPlainObject(value)) {
+        const entries = Object.keys(value).sort().map((key) => {
+            if (!validUnicode(key))
+                throw new Error('Value is not valid canonical JSON: lone surrogate key.');
+            return `${JSON.stringify(key)}:${serialize(value[key], depth + 1, budget)}`;
+        });
+        return `{${entries.join(',')}}`;
+    }
+    throw new Error('Value is not valid canonical JSON: unsupported value.');
+}
+export function canonicalJson(value) { return serialize(value, 0, { nodes: 0 }); }
+export function canonicalJsonBytes(value) {
+    return Buffer.from(canonicalJson(value), 'utf8');
+}
+function hasDuplicateKeys(source) {
+    const stack = [];
+    let index = 0;
+    let expectingKey = false;
+    while (index < source.length) {
+        const char = source[index];
+        if (char === '{') {
+            stack.push(new Set());
+            expectingKey = true;
+            index += 1;
+            continue;
+        }
+        if (char === '[') {
+            stack.push(null);
+            expectingKey = false;
+            index += 1;
+            continue;
+        }
+        if (char === '}' || char === ']') {
+            stack.pop();
+            expectingKey = false;
+            index += 1;
+            continue;
+        }
+        if (char === ',') {
+            expectingKey = stack.at(-1) instanceof Set;
+            index += 1;
+            continue;
+        }
+        if (char === '"') {
+            let end = index + 1;
+            while (end < source.length) {
+                if (source[end] === '\\') {
+                    end += 2;
+                    continue;
+                }
+                if (source[end] === '"')
+                    break;
+                end += 1;
+            }
+            if (expectingKey && source[end + 1] === ':') {
+                const key = JSON.parse(source.slice(index, end + 1));
+                const keys = stack.at(-1);
+                if (keys.has(key))
+                    return true;
+                keys.add(key);
+                expectingKey = false;
+            }
+            index = end + 1;
+            continue;
+        }
+        index += 1;
+    }
+    return false;
+}
+export function parseCanonicalJson(bytes) {
+    const source = Buffer.from(bytes).toString('utf8');
+    if (!Buffer.from(source, 'utf8').equals(Buffer.from(bytes)) || source.includes('\ufffd'))
+        throw new Error('Payload is not canonical JSON.');
+    if (hasDuplicateKeys(source))
+        throw new Error('Payload contains a duplicate JSON key.');
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        throw new Error('Payload is not canonical JSON.');
+    }
+    if (canonicalJson(value) !== source)
+        throw new Error('Payload is not canonical JSON.');
+    return value;
+}

package/dist/canonical-json.test.js

@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { canonicalJson, canonicalJsonBytes, parseCanonicalJson } from './canonical-json.js';
+test('canonicalizes nested objects, arrays, escapes, unicode, and numbers', () => {
+    const value = { z: [3, { b: '\u20ac', a: '\n' }], a: 1e-7 };
+    assert.equal(canonicalJson(value), '{"a":1e-7,"z":[3,{"a":"\\n","b":"€"}]}');
+    assert.deepEqual(canonicalJsonBytes(value), Buffer.from(canonicalJson(value), 'utf8'));
+});
+test('rejects duplicate keys, lone surrogates, unsafe integers, negative zero, and unsupported values', () => {
+    assert.throws(() => parseCanonicalJson(Buffer.from('{"a":1,"a":1}')), /duplicate/i);
+    for (const value of ['\ud800', Number.MAX_SAFE_INTEGER + 1, -0, undefined]) {
+        assert.throws(() => canonicalJson(value), /canonical/i);
+    }
+});
+test('requires exact canonical payload bytes', () => {
+    assert.deepEqual(parseCanonicalJson(Buffer.from('{"a":1,"b":2}')), { a: 1, b: 2 });
+    assert.throws(() => parseCanonicalJson(Buffer.from('{ "a": 1, "b": 2 }')), /canonical/i);
+});
+test('rejects inputs beyond the canonical complexity budget', () => {
+    let value = 1;
+    for (let index = 0; index < 70; index += 1)
+        value = [value];
+    assert.throws(() => canonicalJson(value), /complexity limit/);
+});

package/dist/cli.js

@@ -1,20 +1,146 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync } from 'node:fs';
-import { rules, RULESET_VERSION } from './ai-editor.js';
+import { closeSync, constants, fstatSync, linkSync, mkdtempSync, openSync, readFileSync, readSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
+import { RULESET_VERSION, serializedRules } from './ai-editor.js';
 import { parseCopySpec } from './copy-spec.js';
 import { analyzeBatch, parseWritingBrief } from './editorial-packs.js';
-import { addLearningInstruction, clearLearning, composeLearning, profileFingerprint, recordVerifiedCandidate } from './learning.js';
+import { clearLearning, composeLearning, inspectLearning, migrateLearningV2ToV3, profileFingerprint, ratifyLearningEvent, recordLearningInstruction, supersedeLearningEvent } from './learning.js';
+import { cleanHygiene, finalOutputCheck, inspectHygiene } from './hygiene.js';
 import { analyze, rewritePrompt, verify, verifyWithCopySpec } from './pipeline.js';
 import { parseProfile } from './profile.js';
 import { evaluateRewriteResponse, parseRewriteTask, prepareRewriteTask } from './rewrite-task.js';
+import { parseJudgmentEnvelope, preparePostCandidateJudgment, preparePreEditJudgment, reducePostCandidate, reducePreEdit } from './judgment-task.js';
+import { evaluateRebuildResponse, parseRebuildTask, prepareRebuildTask } from './rebuild-task.js';
+import { canonicalJson, parseCanonicalJson } from './canonical-json.js';
+import { finalizeLifecycle, inspectLifecycle, prepareLifecycle, recordApprovedLearning, submitSemanticVerdict, validateFinalApproval } from './lifecycle-adapter.js';
 import { buildProfile } from './voice-dna.js';
-const usage = 'Commands: profile, analyze, batch-analyze, rewrite-prompt, prepare-rewrite, apply-rewrite, verify, verify-spec, learning, patterns, mcp';
+import { loadApprovalContext } from './approval-context.js';
+const usage = 'Commands: profile, analyze, hygiene, final-check, batch-analyze, rewrite-prompt, prepare-rewrite, apply-rewrite, prepare-judgment, reduce-judgment, prepare-rebuild, apply-rebuild, verify, verify-spec, lifecycle, learning, patterns, mcp';
+const MAX_JSON_BYTES = 1024 * 1024;
 function input(path) {
     return path === '-' ? readFileSync(0, 'utf8') : readFileSync(path, 'utf8');
 }
+function parseBoundedJson(text) {
+    if (Buffer.byteLength(text, 'utf8') > MAX_JSON_BYTES)
+        throw new Error('JSON input exceeds the byte limit.');
+    const value = JSON.parse(text);
+    canonicalJson(value);
+    return value;
+}
+function readBoundedDescriptor(descriptor) {
+    const chunks = [];
+    let size = 0;
+    while (size <= MAX_JSON_BYTES) {
+        const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, MAX_JSON_BYTES + 1 - size));
+        const count = readSync(descriptor, chunk, 0, chunk.length, null);
+        if (!count)
+            break;
+        chunks.push(chunk.subarray(0, count));
+        size += count;
+    }
+    if (size > MAX_JSON_BYTES)
+        throw new Error('JSON input exceeds the byte limit.');
+    return Buffer.concat(chunks, size).toString('utf8');
+}
+function readJson(path) {
+    if (path === '-')
+        return parseBoundedJson(readBoundedDescriptor(0));
+    let descriptor;
+    try {
+        descriptor = openSync(path, constants.O_RDONLY);
+        return parseBoundedJson(readBoundedDescriptor(descriptor));
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}
+function capabilityArguments(args) {
+    const values = [];
+    let source;
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === '--capability-stdin') {
+            if (source)
+                throw new Error('Choose one capability source.');
+            source = { kind: 'stdin' };
+            continue;
+        }
+        if (args[index] === '--capability-file') {
+            const path = args[index + 1];
+            if (source || !path || path.startsWith('--capability-'))
+                throw new Error('Choose one capability source.');
+            source = { kind: 'file', path };
+            index += 1;
+            continue;
+        }
+        values.push(args[index]);
+    }
+    if (!source)
+        return { values };
+    if (source.kind === 'stdin' && values.includes('-'))
+        throw new Error('Capability stdin cannot be combined with another stdin input.');
+    let raw;
+    if (source.kind === 'stdin')
+        raw = readBoundedDescriptor(0);
+    else {
+        let descriptor;
+        try {
+            descriptor = openSync(source.path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+            const before = fstatSync(descriptor);
+            if (!before.isFile() || before.uid !== process.geteuid?.() || (before.mode & 0o077) !== 0 || before.nlink !== 1 || before.size > MAX_JSON_BYTES)
+                throw new Error('Capability file is unavailable or unsafe.');
+            raw = readBoundedDescriptor(descriptor);
+            const after = fstatSync(descriptor);
+            if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs)
+                throw new Error('Capability file is unavailable or unsafe.');
+        }
+        catch {
+            throw new Error('Capability file is unavailable or unsafe.');
+        }
+        finally {
+            if (descriptor !== undefined)
+                closeSync(descriptor);
+        }
+    }
+    if (Buffer.byteLength(raw, 'utf8') > MAX_JSON_BYTES)
+        throw new Error('JSON input exceeds the byte limit.');
+    return { values, capability: parseCanonicalJson(Buffer.from(raw, 'utf8')) };
+}
 function readProfile(path) {
     return parseProfile(JSON.parse(input(path)));
 }
+function requireProfileV3(profile) {
+    if (profile.version !== '3')
+        throw new Error('This learning operation requires a Profile v3.');
+    return profile;
+}
+function learningArguments(args) {
+    const values = [];
+    const options = {};
+    for (const argument of args) {
+        if (!argument.startsWith('--')) {
+            values.push(argument);
+            continue;
+        }
+        const [name, ...parts] = argument.slice(2).split('=');
+        const value = parts.join('=').trim();
+        if (!value)
+            throw new Error(`Learning option --${name} requires a value.`);
+        if (name === 'mutation-id' && value.length <= 200)
+            options.mutationId = value;
+        else if (name === 'authority' && ['founder', 'team', 'system'].includes(value))
+            options.authority = value;
+        else if (name === 'provenance' && value.length <= 500)
+            options.provenance = value;
+        else if (name === 'weight' && Number.isFinite(Number(value)) && Number(value) > 0)
+            options.weight = Number(value);
+        else if (name === 'compatibility' && ['same-or-newer', 'exact'].includes(value))
+            options.compatibility = value;
+        else
+            throw new Error(`Invalid learning option: --${name}=${value}`);
+    }
+    return { values, options };
+}
 function readBrief(path) {
     return path ? parseWritingBrief(JSON.parse(input(path))) : undefined;
 }
@@ -51,6 +177,7 @@ function prepareContext(paths) {
 function json(value) {
     console.log(JSON.stringify(value, null, 2));
 }
+function canonical(value) { process.stdout.write(`${canonicalJson(value)}\n`); }
 function profileArguments(args) {
     const [output, ...rest] = args;
     const samples = [];
@@ -70,6 +197,58 @@ function profileArguments(args) {
         throw new Error('Usage: hyv profile profile.json sample-a.md sample-b.md [sample-c.md] [--avoid=phrase]');
     return { output, samples, avoid };
 }
+function cleanedPath(path) {
+    const extension = extname(path);
+    const stem = extension ? path.slice(0, -extension.length) : path;
+    return `${stem}.cleaned${extension}`;
+}
+function hygieneArguments(args) {
+    const [path, ...options] = args;
+    if (!path)
+        throw new Error('Usage: hyv hygiene draft.md [--fix] [--output=cleaned.md]');
+    let fix = false;
+    let output;
+    for (const option of options) {
+        if (option === '--fix')
+            fix = true;
+        else if (option.startsWith('--output='))
+            output = option.slice('--output='.length).trim();
+        else
+            throw new Error('Usage: hyv hygiene draft.md [--fix] [--output=cleaned.md]');
+    }
+    if (output !== undefined && (!output || !fix))
+        throw new Error('--output requires --fix and a non-empty path.');
+    return { path, fix, ...(output ? { output } : {}) };
+}
+function writeNewFileAtomically(path, text) {
+    const temporaryDirectory = mkdtempSync(join(dirname(resolve(path)), '.hyv-hygiene-'));
+    const temporaryPath = join(temporaryDirectory, 'cleaned');
+    let primaryError;
+    try {
+        writeFileSync(temporaryPath, text, 'utf8');
+        try {
+            linkSync(temporaryPath, path);
+        }
+        catch (error) {
+            const code = error.code;
+            if (!['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'EXDEV'].includes(code ?? ''))
+                throw error;
+            throw new Error(`Atomic hygiene output is not supported by this filesystem: ${path}`);
+        }
+    }
+    catch (error) {
+        primaryError = error.code === 'EEXIST' ? new Error(`Hygiene output already exists: ${path}`) : error;
+    }
+    try {
+        rmSync(temporaryDirectory, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (!primaryError)
+            console.error(`Warning: output was published, but temporary-file cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (primaryError)
+        throw primaryError;
+}
 export async function runCli(args) {
     const [command, ...rest] = args;
     if (command === 'profile') {
@@ -84,6 +263,37 @@ export async function runCli(args) {
         json(analyze(input(draft), readProfile(profilePath), readBrief(briefPath)));
         return 0;
     }
+    if (command === 'hygiene') {
+        const { path, fix, output } = hygieneArguments(rest);
+        if (fix && path === '-')
+            throw new Error('hyv hygiene --fix requires a file path so the original can be preserved.');
+        const text = input(path);
+        if (!fix) {
+            json(inspectHygiene(text));
+            return 0;
+        }
+        const outputPath = output ?? cleanedPath(path);
+        if (resolve(outputPath) === resolve(path))
+            throw new Error('Hygiene output must differ from the input path.');
+        const result = cleanHygiene(text);
+        writeNewFileAtomically(outputPath, result.cleaned);
+        json({ ...result.report, changed: result.changed, changes: result.changes, outputPath });
+        return 0;
+    }
+    if (command === 'final-check') {
+        const [path, ...options] = rest;
+        if (!path || options.length)
+            throw new Error('Usage: hyv final-check <path|->');
+        const result = finalOutputCheck(input(path));
+        if (!result.accepted) {
+            console.error(JSON.stringify(result, null, 2));
+            return 2;
+        }
+        if (result.changed)
+            console.error(JSON.stringify({ changed: true, changes: result.changes }, null, 2));
+        process.stdout.write(result.output);
+        return 0;
+    }
     if (command === 'batch-analyze') {
         if (rest.length < 2)
             throw new Error('Usage: hyv batch-analyze draft-a.md draft-b.md [draft-c.md]');
@@ -116,6 +326,50 @@ export async function runCli(args) {
         json(result);
         return result.status === 'accepted' ? 0 : 2;
     }
+    if (command === 'prepare-judgment') {
+        const [stage, kind, draft, profilePath, output, candidatePath] = rest;
+        if (!stage || !kind || !draft || !profilePath || !output)
+            throw new Error('Usage: hyv prepare-judgment pre-edit|post-candidate kind draft.md profile.json task.json [candidate.md]');
+        if (stage === 'post-candidate' && !candidatePath)
+            throw new Error('Usage: hyv prepare-judgment post-candidate kind draft.md profile.json task.json candidate.md');
+        const profile = readProfile(profilePath);
+        const task = stage === 'pre-edit'
+            ? preparePreEditJudgment(input(draft), profile, kind)
+            : preparePostCandidateJudgment(input(draft), input(candidatePath ?? ''), profile, kind);
+        writeFileSync(output, `${JSON.stringify(task, null, 2)}\n`);
+        json({ version: task.version, stage: task.stage, judgmentType: task.judgmentType, taskFingerprint: task.taskFingerprint });
+        return 0;
+    }
+    if (command === 'reduce-judgment') {
+        if (rest.length < 3)
+            throw new Error('Usage: hyv reduce-judgment envelope.json envelope.json [envelope.json...]');
+        const envelopes = rest.map((path) => parseJudgmentEnvelope(JSON.parse(input(path))));
+        const stage = envelopes[0]?.stage;
+        json(stage === 'pre-edit' ? reducePreEdit(envelopes) : reducePostCandidate(envelopes));
+        return 0;
+    }
+    if (command === 'prepare-rebuild') {
+        const { values, capability } = capabilityArguments(rest);
+        const [draft, profilePath, reductionPath, specPath, output, briefPath] = values;
+        if (!draft || !profilePath || !reductionPath || !specPath || !output || !capability) {
+            throw new Error('Usage: hyv prepare-rebuild draft.md profile.json reduction.json copy-spec.json task.json [writing-brief.json] (--capability-stdin|--capability-file path)');
+        }
+        const context = loadApprovalContext();
+        const task = prepareRebuildTask(input(draft), readProfile(profilePath), readJson(reductionPath), parseCopySpec(JSON.parse(input(specPath))), capability, context.trustStore, context.now, briefPath ? parseWritingBrief(JSON.parse(input(briefPath))) : undefined);
+        writeFileSync(output, `${JSON.stringify(task, null, 2)}\n`);
+        json({ version: task.version, fingerprint: task.fingerprint, recommendationFingerprint: task.recommendationFingerprint, authorizationFingerprint: task.authorizationFingerprint });
+        return 0;
+    }
+    if (command === 'apply-rebuild') {
+        const { values, capability } = capabilityArguments(rest);
+        const [taskPath, responsePath, profilePath, ...extra] = values;
+        if (!taskPath || !responsePath || !profilePath || extra.length || !capability)
+            throw new Error('Usage: hyv apply-rebuild task.json response.json profile.json (--capability-stdin|--capability-file path)');
+        const context = loadApprovalContext();
+        const result = evaluateRebuildResponse(parseRebuildTask(JSON.parse(input(taskPath))), input(responsePath), readProfile(profilePath), capability, context.trustStore, context.now);
+        json(result);
+        return result.status === 'accepted' ? 0 : 2;
+    }
     if (command === 'verify') {
         const [original, candidate, profilePath, briefPath] = rest;
         if (!original || !candidate || !profilePath)
@@ -124,9 +378,6 @@ export async function runCli(args) {
         const originalText = input(original);
         const candidateText = input(candidate);
         const result = verify(originalText, candidateText, profile, readBrief(briefPath));
-        const learning = recordVerifiedCandidate(profile, result, candidateText);
-        if (learning === 'write_failed')
-            console.error('Warning: verification passed, but local learning could not be saved.');
         json(result);
         return result.passed ? 0 : 2;
     }
@@ -137,38 +388,125 @@ export async function runCli(args) {
         const profile = readProfile(profilePath);
         const candidateText = input(candidate);
         const result = verifyWithCopySpec(input(original), candidateText, profile, parseCopySpec(JSON.parse(input(specPath))), readBrief(briefPath));
-        if (result.passed) {
-            const learning = recordVerifiedCandidate(profile, result, candidateText);
-            if (learning === 'write_failed')
-                console.error('Warning: verification passed, but local learning could not be saved.');
-        }
         json(result);
         return result.passed ? 0 : 2;
     }
+    if (command === 'lifecycle') {
+        const [action, ...raw] = rest;
+        if (action === 'prepare-semantic') {
+            const [deterministicPath, bindingPath, receiptPath, policy, violationsPath, output, ...extra] = raw;
+            if (!deterministicPath || !bindingPath || !receiptPath || !policy || !violationsPath || !output || extra.length || !['normal', 'high_assurance'].includes(policy))
+                throw new Error('Usage: hyv lifecycle prepare-semantic deterministic.json binding.json receipt.json <normal|high_assurance> violations.json output.json');
+            if (policy === 'high_assurance')
+                throw new Error('High-assurance semantic review requires a trusted embedding.');
+            const result = prepareLifecycle(readJson(deterministicPath), readJson(bindingPath), readJson(receiptPath), policy, readJson(violationsPath));
+            const serialized = canonicalJson(result);
+            writeFileSync(output, `${serialized}\n`, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+            process.stdout.write(`${serialized}\n`);
+            return 0;
+        }
+        if (action === 'submit-verdict') {
+            const [artifactPath, taskPath, evaluatorId, verdictPath, ...extra] = raw;
+            if (!artifactPath || !taskPath || !evaluatorId || !verdictPath || extra.length)
+                throw new Error('Usage: hyv lifecycle submit-verdict artifact.json task.json evaluator-id verdict.json');
+            const artifact = readJson(artifactPath);
+            const task = readJson(taskPath);
+            if (task.policy !== 'normal')
+                throw new Error('High-assurance semantic review requires a trusted embedding.');
+            const result = submitSemanticVerdict(artifact, task, evaluatorId, readJson(verdictPath), loadApprovalContext());
+            canonical(result.ok ? result.artifact : { error: result.error });
+            return result.ok && result.artifact.status === 'ready_for_human_review' ? 0 : 2;
+        }
+        if (action === 'inspect') {
+            const [artifactPath, ...extra] = raw;
+            if (!artifactPath || extra.length)
+                throw new Error('Usage: hyv lifecycle inspect artifact.json');
+            canonical(inspectLifecycle(readJson(artifactPath)));
+            return 0;
+        }
+        if (action === 'validate-final-approval' || action === 'finalize') {
+            const { values, capability } = capabilityArguments(raw);
+            if (action === 'validate-final-approval') {
+                const [artifactPath, ...extra] = values;
+                if (!artifactPath || extra.length || !capability)
+                    throw new Error('Usage: hyv lifecycle validate-final-approval artifact.json (--capability-stdin|--capability-file path)');
+                const result = validateFinalApproval(readJson(artifactPath), capability, loadApprovalContext());
+                canonical(result);
+                return result.ok ? 0 : 2;
+            }
+            const [artifactPath, decisionPath, ...extra] = values;
+            if (!artifactPath || !decisionPath || extra.length)
+                throw new Error('Usage: hyv lifecycle finalize artifact.json decision.json [--capability-stdin|--capability-file path]');
+            const decision = readJson(decisionPath);
+            if (decision.decision === 'approve' && !capability)
+                throw new Error('Approval requires a capability.');
+            if (decision.decision === 'reject' && capability)
+                throw new Error('Rejection does not accept a capability.');
+            const result = finalizeLifecycle(readJson(artifactPath), decision, loadApprovalContext(), capability);
+            canonical(result.ok ? result.artifact : { error: result.error });
+            return result.ok && result.artifact.status === 'approved' ? 0 : 2;
+        }
+        throw new Error('Usage: hyv lifecycle <prepare-semantic|submit-verdict|inspect|validate-final-approval|finalize> ...');
+    }
     if (command === 'learning') {
-        const [action, profilePath, ...instruction] = rest;
+        const [action, ...raw] = rest;
+        if (action === 'record-approved') {
+            const { values, capability } = capabilityArguments(raw);
+            const [readyPath, approvedPath, originalPath, candidatePath, profilePath, decisionPath, ...contextPaths] = values;
+            if (!readyPath || !approvedPath || !originalPath || !candidatePath || !profilePath || !decisionPath || !capability)
+                throw new Error('Usage: hyv learning record-approved ready.json approved.json original.md candidate.md profile.json decision.json [copy-spec.json] [writing-brief.json] (--capability-stdin|--capability-file path)');
+            const context = prepareContext(contextPaths);
+            const status = recordApprovedLearning({ ready: readJson(readyPath), approved: readJson(approvedPath), decision: readJson(decisionPath), capability, source: input(originalPath), candidate: input(candidatePath), profile: readProfile(profilePath), context: loadApprovalContext(), copySpec: context.copySpec, writingBrief: context.writingBrief });
+            canonical({ status });
+            return status === 'write_failed' ? 2 : 0;
+        }
+        const { values, options } = learningArguments(raw);
+        const [profilePath, ...operands] = values;
         if (!action || !profilePath)
-            throw new Error('Usage: hyv learning <show|add|clear> profile.json [instruction]');
+            throw new Error('Usage: hyv learning <show|inspect|add|record|ratify|supersede|migrate|clear> profile.json [value] [options]');
         const profile = readProfile(profilePath);
         if (action === 'show') {
-            json({ profile: profileFingerprint(profile), preferences: composeLearning(profile) });
+            json({ profile: profileFingerprint(profile), preferences: composeLearning(profile, options) });
+            return 0;
+        }
+        if (action === 'inspect') {
+            if (Object.keys(options).length)
+                throw new Error('Usage: hyv learning inspect profile.json');
+            json(inspectLearning(profile));
             return 0;
         }
-        if (action === 'add') {
-            const text = instruction.join(' ').trim();
+        if (action === 'add' || action === 'record') {
+            const text = operands.join(' ').trim();
             if (!text)
-                throw new Error('Usage: hyv learning add profile.json "instruction"');
-            json({ added: addLearningInstruction(profile, text) });
+                throw new Error('Usage: hyv learning record profile.json "instruction" [options]');
+            const result = recordLearningInstruction(profile, text, options);
+            json(action === 'add' ? { added: result.status === 'recorded' } : result);
+            return 0;
+        }
+        if (action === 'ratify' || action === 'supersede') {
+            const [eventId, ...extra] = operands;
+            if (!eventId || extra.length)
+                throw new Error(`Usage: hyv learning ${action} profile.json event-id [options]`);
+            json(action === 'ratify' ? ratifyLearningEvent(requireProfileV3(profile), eventId, options) : supersedeLearningEvent(requireProfileV3(profile), eventId, options));
+            return 0;
+        }
+        if (action === 'migrate') {
+            const [targetPath, ...extra] = operands;
+            if (!targetPath || extra.length || profile.version !== '2')
+                throw new Error('Usage: hyv learning migrate source-v2.json target-v3.json [options]');
+            json(migrateLearningV2ToV3(profile, requireProfileV3(readProfile(targetPath)), options));
             return 0;
         }
         if (action === 'clear') {
+            if (operands.length || Object.keys(options).length)
+                throw new Error('Usage: hyv learning clear profile.json');
             json({ cleared: clearLearning(profile) });
             return 0;
         }
-        throw new Error('Usage: hyv learning <show|add|clear> profile.json [instruction]');
+        throw new Error('Usage: hyv learning <show|inspect|add|record|ratify|supersede|migrate|clear> profile.json [value] [options]');
     }
     if (command === 'patterns') {
-        json({ version: RULESET_VERSION, rules: rules.map(({ expression, ...rule }) => ({ ...rule, expression: expression.source })) });
+        json({ version: RULESET_VERSION, rules: serializedRules() });
         return 0;
     }
     if (command === 'mcp') {