@holdyourvoice/hyv 3.3.5 → 3.4.0

package/dist/agents/load.test.js

@@ -0,0 +1,149 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadAll, loadAllFrom, validateAll, validateId, sortedIds } from './load.js';
+import { AGENT_SCHEMA_VERSION } from './types.js';
+function makePackage(dir, id, overrides = {}) {
+    const packageDir = join(dir, 'skills', id);
+    mkdirSync(join(packageDir, 'agents'), { recursive: true });
+    const descriptor = {
+        schema_version: AGENT_SCHEMA_VERSION,
+        id,
+        title: id,
+        description: 'test agent',
+        instruction_file: 'SKILL.md',
+        role: 'Tester',
+        workflow_phase: 'test',
+        input: { required: ['draft'], optional: [] },
+        output: { required: ['report'], optional: [] },
+        evidence_requirements: ['preserve evidence'],
+        permissions: ['read_repository'],
+        stop_conditions: ['stop when evidence missing'],
+        tool_free_mode: {
+            available: true,
+            behavior: 'report NOT_AVAILABLE',
+            unavailable_statuses: ['NOT_AVAILABLE', 'NOT_RUN'],
+        },
+        handoff_to: [],
+        ...overrides,
+    };
+    writeFileSync(join(packageDir, 'agent.json'), JSON.stringify(descriptor));
+    writeFileSync(join(packageDir, 'SKILL.md'), `# ${id}\n\nUsage: hyv ${id} draft.md\n`);
+    writeFileSync(join(packageDir, 'agents', 'openai.yaml'), `interface:\n  display_name: "${id}"\n  short_description: "test agent"\n  default_prompt: "Use ${id}"\n`);
+    return packageDir;
+}
+function makeTempRoot() {
+    return mkdtempSync(join(tmpdir(), 'hyv-agents-'));
+}
+test('loads all valid packages and rejects unknown schema version', () => {
+    const root = makeTempRoot();
+    try {
+        const first = makePackage(root, 'hyv-alpha');
+        makePackage(root, 'hyv-beta', { handoff_to: ['hyv-alpha'] });
+        const packages = loadAllFrom(root);
+        assert.deepEqual(sortedIds(packages), ['hyv-alpha', 'hyv-beta']);
+        assert.equal(packages.get('hyv-alpha').directory, first);
+        assert.match(packages.get('hyv-alpha').instructions, /^# hyv-alpha/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('rejects a package whose id does not match its directory name', () => {
+    const root = makeTempRoot();
+    try {
+        makePackage(root, 'hyv-alpha', { id: 'hyv-mismatch' });
+        assert.throws(() => loadAllFrom(root), /id must match skill directory/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('rejects a handoff target that does not exist', () => {
+    const root = makeTempRoot();
+    try {
+        makePackage(root, 'hyv-alpha', { handoff_to: ['hyv-ghost'] });
+        assert.throws(() => loadAllFrom(root), /hands off to unknown agent/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('rejects an unsupported permission and an unsupported status', () => {
+    const root = makeTempRoot();
+    try {
+        makePackage(root, 'hyv-alpha', { permissions: ['definitely-not-real'] });
+        assert.throws(() => loadAllFrom(root), /unsupported permission/);
+        rmSync(root, { recursive: true, force: true });
+        const root2 = makeTempRoot();
+        makePackage(root2, 'hyv-beta', {
+            tool_free_mode: { available: true, behavior: 'x', unavailable_statuses: ['NOPE'] },
+        });
+        assert.throws(() => loadAllFrom(root2), /tool_free_mode requires/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('validateAll and validateId report PASS or unknown id', () => {
+    const root = makeTempRoot();
+    try {
+        makePackage(root, 'hyv-alpha');
+        const packages = loadAllFrom(root);
+        validateAll(packages);
+        validateId(packages, 'hyv-alpha');
+        assert.throws(() => validateId(packages, 'hyv-missing'), /unknown agent/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('rejects a malformed agent.json', () => {
+    const root = makeTempRoot();
+    try {
+        const packageDir = join(root, 'skills', 'hyv-alpha');
+        mkdirSync(join(packageDir, 'agents'), { recursive: true });
+        writeFileSync(join(packageDir, 'agent.json'), '{ not json');
+        writeFileSync(join(packageDir, 'SKILL.md'), '# x');
+        assert.throws(() => loadAllFrom(root), /not valid JSON/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('rejects unknown contract fields and invalid OpenAI interface metadata', () => {
+    const root = makeTempRoot();
+    try {
+        makePackage(root, 'hyv-alpha', { unsupported: true });
+        assert.throws(() => loadAllFrom(root), /supported contract fields/);
+        rmSync(root, { recursive: true, force: true });
+        const root2 = makeTempRoot();
+        const packageDir = makePackage(root2, 'hyv-beta');
+        rmSync(join(packageDir, 'agents', 'openai.yaml'));
+        assert.throws(() => loadAllFrom(root2), /openai\.yaml/);
+        rmSync(root2, { recursive: true, force: true });
+        const root3 = makeTempRoot();
+        const invalidPackageDir = makePackage(root3, 'hyv-gamma');
+        writeFileSync(join(invalidPackageDir, 'agents', 'openai.yaml'), 'interface:\n  display_name: "unterminated\n  short_description: "test"\n  default_prompt: "Use hyv-gamma"\n');
+        assert.throws(() => loadAllFrom(root3), /supported interface metadata/);
+        rmSync(root3, { recursive: true, force: true });
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('published packages declare command execution and required writes', () => {
+    const packages = loadAll();
+    const writers = new Set(['hyv-profile', 'hyv-hygiene', 'hyv-apply-hidden-text-policy', 'hyv-prepare-rewrite', 'hyv-prepare-judgment', 'hyv-prepare-rebuild', 'hyv-rebuild-writer-request', 'hyv-lifecycle', 'hyv-learning']);
+    for (const [id, pkg] of packages) {
+        assert.ok(pkg.descriptor.permissions.includes('execute_commands'), `${id} must require command execution`);
+        assert.equal(pkg.descriptor.permissions.includes('write_repository'), writers.has(id), `${id} write permission mismatch`);
+    }
+});
+test('published instructions document command-specific argument requirements', () => {
+    const packages = loadAll();
+    assert.match(packages.get('hyv-reduce-judgment').instructions, /hyv reduce-judgment envelope\.json envelope\.json envelope\.json \[envelope\.json\.\.\.\]/);
+    assert.match(packages.get('hyv-learning').instructions, /record-approved/);
+});

package/dist/agents/types.js

@@ -0,0 +1,18 @@
+export const AGENT_SCHEMA_VERSION = '1.0.0';
+export const VALID_PERMISSIONS = new Set([
+    'read_repository',
+    'write_repository',
+    'execute_commands',
+    'network',
+    'browser_automation',
+    'git_write',
+    'pull_request_write',
+    'subagents',
+]);
+export const VALID_UNAVAILABLE_STATUSES = new Set([
+    'NOT_AVAILABLE',
+    'NOT_CONFIGURED',
+    'NOT_RUN',
+    'STALE',
+    'ERROR',
+]);

package/dist/cli.js

@@ -19,7 +19,8 @@ import { buildProfile } from './voice-dna.js';
 import { loadApprovalContext } from './approval-context.js';
 import { formatFactLintReport, lintFacts } from './fact-linter.js';
 import { lintLogic } from './logic-linter.js';
-const usage = 'Commands: profile, analyze, hygiene, inspect-hidden-text, apply-hidden-text-policy, final-check, fact-lint, logic-lint, batch-analyze, rewrite-prompt, prepare-rewrite, apply-rewrite, prepare-judgment, reduce-judgment, prepare-rebuild, rebuild-writer-request, apply-rebuild, verify, verify-spec, lifecycle, learning, patterns, mcp';
+import { loadAll, validateAll, validateId, sortedIds, describe, emitJson, emitPrompt } from './agents/index.js';
+const usage = 'Commands: agent, profile, analyze, hygiene, inspect-hidden-text, apply-hidden-text-policy, final-check, fact-lint, logic-lint, batch-analyze, rewrite-prompt, prepare-rewrite, apply-rewrite, prepare-judgment, reduce-judgment, prepare-rebuild, rebuild-writer-request, apply-rebuild, verify, verify-spec, lifecycle, learning, patterns, mcp';
 function input(path) {
     return path === '-' ? readFileSync(0, 'utf8') : readFileSync(path, 'utf8');
 }
@@ -269,8 +270,116 @@ function writeNewFileAtomically(path, text) {
     if (primaryError)
         throw primaryError;
 }
+function agentFlags(args) {
+    const values = [];
+    let host = 'generic';
+    let mode;
+    let output;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--host') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('--'))
+                throw new Error('Usage: hyv agent --host HOST requires a value.');
+            host = value;
+            index += 1;
+        }
+        else if (argument.startsWith('--host=')) {
+            const value = argument.slice('--host='.length);
+            if (!value)
+                throw new Error('Usage: hyv agent --host HOST requires a value.');
+            host = value;
+        }
+        else if (argument === '--mode') {
+            const value = args[index + 1];
+            if (value !== 'prompt' && value !== 'json')
+                throw new Error('Usage: hyv agent --mode prompt|json requires a mode.');
+            mode = value;
+            index += 1;
+        }
+        else if (argument.startsWith('--mode=')) {
+            const value = argument.slice('--mode='.length);
+            if (value !== 'prompt' && value !== 'json')
+                throw new Error('Usage: hyv agent --mode prompt|json requires a mode.');
+            mode = value;
+        }
+        else if (argument === '--output') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('--'))
+                throw new Error('Usage: hyv agent --output FILE requires a value.');
+            output = value;
+            index += 1;
+        }
+        else if (argument.startsWith('--output=')) {
+            const value = argument.slice('--output='.length);
+            if (!value)
+                throw new Error('Usage: hyv agent --output FILE requires a value.');
+            output = value;
+        }
+        else {
+            values.push(argument);
+        }
+    }
+    return { values, host, mode, output };
+}
+function runAgent(args) {
+    const [subcommand, ...subargs] = args;
+    if (subcommand === 'list') {
+        if (subargs.length)
+            throw new Error('Usage: hyv agent list');
+        const packages = loadAll();
+        const ids = sortedIds(packages);
+        json(ids.map((id) => {
+            const descriptor = packages.get(id).descriptor;
+            return { id, role: descriptor.role, workflow_phase: descriptor.workflow_phase, description: descriptor.description };
+        }));
+        return 0;
+    }
+    if (subcommand === 'validate') {
+        if (subargs.length > 1)
+            throw new Error('Usage: hyv agent validate [id]');
+        const packages = loadAll();
+        const id = subargs[0];
+        if (id !== undefined)
+            validateId(packages, id);
+        validateAll(packages);
+        json({ schema_version: '1.0.0', status: 'PASS', agent: id ?? 'all' });
+        return 0;
+    }
+    if (subcommand === 'describe') {
+        const { values, host, mode, output } = agentFlags(subargs);
+        if (values.length !== 1 || mode !== undefined || output !== undefined)
+            throw new Error('Usage: hyv agent describe <id> [--host HOST]');
+        const packages = loadAll();
+        validateId(packages, values[0]);
+        json(describe(packages.get(values[0]), host));
+        return 0;
+    }
+    if (subcommand === 'emit') {
+        const { values, host, mode, output } = agentFlags(subargs);
+        if (values.length !== 1)
+            throw new Error('Usage: hyv agent emit <id> --mode prompt|json [--host HOST] [--output FILE]');
+        if (!mode)
+            throw new Error('Usage: hyv agent emit <id> --mode prompt|json [--host HOST] [--output FILE]');
+        const packages = loadAll();
+        validateId(packages, values[0]);
+        const pkg = packages.get(values[0]);
+        const body = mode === 'prompt' ? emitPrompt(pkg, host) : `${emitJson(pkg, host)}\n`;
+        if (output !== undefined) {
+            writeFileSync(output, body, { encoding: 'utf8', flag: 'wx' });
+        }
+        else {
+            process.stdout.write(body);
+        }
+        return 0;
+    }
+    throw new Error('Usage: hyv agent <list|validate|describe|emit> ...');
+}
 export async function runCli(args) {
     const [command, ...rest] = args;
+    if (command === 'agent') {
+        return runAgent(rest);
+    }
     if (command === 'profile') {
         const { output, samples, avoid } = profileArguments(rest);
         writeFileSync(output, `${JSON.stringify(buildProfile(samples.map(input), avoid), null, 2)}\n`);

package/dist/cli.test.js

@@ -556,3 +556,79 @@ test('prepares and applies an authorized rebuild through CLI', () => {
         rmSync(directory, { recursive: true, force: true });
     }
 });
+test('agent list enumerates every command as one portable package', () => {
+    const result = run(['agent', 'list']);
+    assert.equal(result.status, 0, result.stderr);
+    const entries = JSON.parse(result.stdout);
+    assert.equal(entries.length, 23);
+    const ids = entries.map((entry) => entry.id);
+    assert.equal(new Set(ids).size, ids.length);
+    for (const id of ['hyv-profile', 'hyv-analyze', 'hyv-verify', 'hyv-mcp', 'hyv-patterns']) {
+        assert.ok(ids.includes(id), `missing ${id}`);
+    }
+    for (const entry of entries) {
+        assert.ok(entry.role);
+        assert.ok(entry.workflow_phase);
+        assert.ok(entry.description);
+    }
+});
+test('agent validate passes over the full package tree and rejects unknown ids', () => {
+    const result = run(['agent', 'validate']);
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(JSON.parse(result.stdout).status, 'PASS');
+    assert.equal(run(['agent', 'validate', 'hyv-verify']).status, 0);
+    const unknown = run(['agent', 'validate', 'hyv-does-not-exist']);
+    assert.equal(unknown.status, 1);
+    assert.match(unknown.stderr, /unknown agent/);
+});
+test('agent describe resolves a host and reports the runtime descriptor', () => {
+    const result = run(['agent', 'describe', 'hyv-verify', '--host', 'codex']);
+    assert.equal(result.status, 0, result.stderr);
+    const descriptor = JSON.parse(result.stdout);
+    assert.equal(descriptor.agent.id, 'hyv-verify');
+    assert.equal(descriptor.host.id, 'codex');
+    assert.ok(descriptor.available_capabilities.includes('read_repository'));
+    assert.ok(Array.isArray(descriptor.unavailable_capabilities));
+});
+test('agent emit writes a prompt or json contract to stdout or a named file', () => {
+    const prompt = run(['agent', 'emit', 'hyv-verify', '--mode=prompt', '--host=generic']);
+    assert.equal(prompt.status, 0, prompt.stderr);
+    assert.match(prompt.stdout, /# hyv-verify/);
+    assert.match(prompt.stdout, /Required input: original path, candidate path, profile path/);
+    const jsonOut = run(['agent', 'emit', 'hyv-verify', '--mode', 'json', '--host', 'generic']);
+    assert.equal(jsonOut.status, 0, jsonOut.stderr);
+    assert.equal(JSON.parse(jsonOut.stdout).agent.id, 'hyv-verify');
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-agent-'));
+    try {
+        const target = join(directory, 'verify.json');
+        const emitted = run(['agent', 'emit', 'hyv-verify', '--mode', 'json', '--output', target]);
+        assert.equal(emitted.status, 0, emitted.stderr);
+        assert.equal(JSON.parse(readFileSync(target, 'utf8')).agent.id, 'hyv-verify');
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('agent commands locate the installed package tree outside a repository', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-agent-cwd-'));
+    try {
+        mkdirSync(join(directory, 'skills'));
+        const result = spawnSync(process.execPath, [cli, 'agent', 'validate'], { cwd: directory, encoding: 'utf8' });
+        assert.equal(result.status, 0, result.stderr);
+        assert.equal(JSON.parse(result.stdout).status, 'PASS');
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('agent usage errors return exit 1 and never mutate', () => {
+    assert.equal(run(['agent']).status, 1);
+    assert.equal(run(['agent', 'emit', 'hyv-verify']).status, 1);
+    assert.equal(run(['agent', 'emit', 'hyv-verify', '--mode', 'bad']).status, 1);
+    assert.equal(run(['agent', 'describe']).status, 1);
+    assert.equal(run(['agent', 'describe', 'hyv-verify', '--mode', 'json']).status, 1);
+    assert.equal(run(['agent', 'describe', 'hyv-verify', '--output', 'ignored.json']).status, 1);
+    assert.equal(run(['agent', 'list', '--host', 'codex']).status, 1);
+    assert.equal(run(['agent', 'list', 'extra']).status, 1);
+    assert.equal(run(['agent', 'nope']).status, 1);
+});

package/dist/rebuild-task.test.js

@@ -174,7 +174,7 @@ test('CLI and MCP rebuild helpers share fingerprints', () => {
         version: '1', audience: 'operators', intent: 'explain', format: 'outreach',
     });
     assert.match(briefTask.prompt, /# WritingBrief/);
-    assert.equal(HYV_VERSION, '3.3.5');
+    assert.equal(HYV_VERSION, '3.4.0');
 });
 test('apply rejects forged tasks, missing capability, and substituted profiles', () => {
     const reduction = rebuildRecommendation();

package/dist/release-audit.test.js

@@ -23,7 +23,7 @@ function fixture(files) {
     const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-audit-'));
     execFileSync('git', ['init', '--quiet'], { cwd: directory });
     const defaults = {
-        'package.json': JSON.stringify({ name: 'audit-fixture', license: 'MIT', files: ['dist', 'Readme.md', 'LICENSE'], scripts: { 'stage1:evaluate': 'node scripts/evaluate-rewrite-benchmark.mjs', 'stage1:dry-run': 'npm run build && node scripts/run-stage1-dry-run.mjs', 'stage1:human-packet': 'npm run build && node scripts/run-stage1-human-packet.mjs', 'stage2:human-packet': 'npm run build && node scripts/run-stage2-human-packet.mjs' }, version: '1.0.0', type: 'module', bin: { hyv: 'dist/cli.js' }, engines: { node: '>=20' } }),
+        'package.json': JSON.stringify({ name: 'audit-fixture', license: 'MIT', files: ['dist', 'skills', 'Readme.md', 'LICENSE'], scripts: { 'stage1:evaluate': 'node scripts/evaluate-rewrite-benchmark.mjs', 'stage1:dry-run': 'npm run build && node scripts/run-stage1-dry-run.mjs', 'stage1:human-packet': 'npm run build && node scripts/run-stage1-human-packet.mjs', 'stage2:human-packet': 'npm run build && node scripts/run-stage2-human-packet.mjs' }, version: '1.0.0', type: 'module', bin: { hyv: 'dist/cli.js' }, engines: { node: '>=20' } }),
         'mcpb/manifest.json': JSON.stringify({ version: '1.0.0' }),
         'claude-plugin/.claude-plugin/plugin.json': JSON.stringify({ version: '1.0.0' }),
         '.claude-plugin/marketplace.json': JSON.stringify({ plugins: [{ name: 'hold-your-voice', version: '1.0.0' }] }),
@@ -36,6 +36,9 @@ function fixture(files) {
         ].join('\n'),
         'src/version.ts': "export const HYV_VERSION = '1.0.0';",
         'src/stage1-evaluation.ts': "const baseline = '4e6269121d551c008a34db73077e1e4fea41b3f9'; const stage1 = '550ea24f652291dca13757fdbd2f0fa0b5e3f621';",
+        'skills/hyv-test/agent.json': '{}',
+        'skills/hyv-test/SKILL.md': '# test',
+        'skills/hyv-test/agents/openai.yaml': 'name: test',
         ...Object.fromEntries(stage1Files.map((file) => [file, '{}'])),
     };
     for (const [file, text] of Object.entries({ ...defaults, ...files })) {
@@ -146,6 +149,7 @@ test('requires the npm package runtime contract', () => {
         const result = spawnSync(process.execPath, [audit], { cwd: directory, encoding: 'utf8' });
         assert.notEqual(result.status, 0);
         assert.match(result.stderr, /npm package must include dist/);
+        assert.match(result.stderr, /npm package must include skills/);
         assert.match(result.stderr, /npm package must include Readme\.md/);
         assert.match(result.stderr, /npm package must use the ESM runtime contract/);
         assert.match(result.stderr, /npm hyv binary must point to dist\/cli\.js/);

package/dist/version.js

@@ -1 +1 @@
-export const HYV_VERSION = '3.3.5';
+export const HYV_VERSION = '3.4.0';

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@holdyourvoice/hyv",
-  "version": "3.3.5",
+  "version": "3.4.0",
   "description": "A local-first dual-engine writing gate that protects voice and catches generic AI patterns.",
   "type": "module",
   "bin": { "hyv": "dist/cli.js" },
-  "files": ["dist", "Readme.md", "LICENSE"],
-  "scripts": { "build": "tsc -p tsconfig.json", "bundle:claude": "esbuild src/mcp.ts --bundle --platform=node --format=esm --target=node20 --outfile=mcpb/server/index.js", "build:claude": "npm run build && npm run bundle:claude", "pack:claude": "npm run build:claude && node scripts/pack-claude.mjs", "stage1:evaluate": "node scripts/evaluate-rewrite-benchmark.mjs", "stage1:dry-run": "npm run build && node scripts/run-stage1-dry-run.mjs", "stage1:human-packet": "npm run build && node scripts/run-stage1-human-packet.mjs", "stage2:human-packet": "npm run build && node scripts/run-stage2-human-packet.mjs", "test": "npm run build && node --test dist/**/*.test.js", "check:release": "node scripts/release-audit.mjs", "prepack": "npm run check:release && npm test" },
+  "files": ["dist", "skills", "Readme.md", "LICENSE"],
+  "scripts": { "build": "tsc -p tsconfig.json", "bundle:claude": "esbuild src/mcp.ts --bundle --platform=node --format=esm --target=node20 --outfile=mcpb/server/index.js", "build:claude": "npm run build && npm run bundle:claude", "pack:claude": "npm run build:claude && node scripts/pack-claude.mjs", "stage1:evaluate": "node scripts/evaluate-rewrite-benchmark.mjs", "stage1:dry-run": "npm run build && node scripts/run-stage1-dry-run.mjs", "stage1:human-packet": "npm run build && node scripts/run-stage1-human-packet.mjs", "stage2:human-packet": "npm run build && node scripts/run-stage2-human-packet.mjs", "test": "npm run build && node --test \"dist/**/*.test.js\"", "check:release": "node scripts/release-audit.mjs", "prepack": "npm run check:release && npm test" },
   "engines": { "node": ">=20" },
   "license": "MIT",
   "keywords": ["ai-writing", "cli", "editing", "voice", "writing"],

package/skills/hyv-analyze/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: hyv-analyze
+description: Run separate VoiceDNA and AI Editor checks plus a non-scoring Unicode hygiene inspection against a draft.
+---
+
+# hyv-analyze
+
+Run independent VoiceDNA and AI Editor reports plus a separate non-scoring Unicode hygiene report against a draft using a portable profile. An optional WritingBrief adds local audience, intent, and format context without changing the profile. Analysis is read-only; it never rewrites the draft or calls a model.
+
+## Usage
+
+```text
+hyv analyze draft.md profile.json [writing-brief.json]
+```
+
+## Behavior
+
+- Deterministic and local-first: this command never calls a provider and never sends drafts, samples, profiles, or telemetry to a service.
+- Commands that write use an explicit output path. Confirm that path before running the command.
+- This agent describes how to invoke the command and what it returns. It does not change command behavior or exit codes.
+
+## Handoff
+
+Run `hyv analyze` directly to execute the operation. Follow-on agents: hyv-rewrite-prompt, hyv-prepare-rewrite.

package/skills/hyv-analyze/agent.json

@@ -0,0 +1,49 @@
+{
+  "schema_version": "1.0.0",
+  "id": "hyv-analyze",
+  "title": "hyv-analyze",
+  "description": "Run separate VoiceDNA and AI Editor checks plus a non-scoring Unicode hygiene inspection against a draft.",
+  "instruction_file": "SKILL.md",
+  "role": "Analyzer",
+  "workflow_phase": "analyze",
+  "input": {
+    "required": [
+      "draft path",
+      "profile path"
+    ],
+    "optional": [
+      "writing-brief.json"
+    ]
+  },
+  "output": {
+    "required": [
+      "combined analysis report"
+    ],
+    "optional": []
+  },
+  "evidence_requirements": [
+    "Report only the deterministic result the command returns; never invent a model or provider call that did not occur."
+  ],
+  "permissions": [
+    "execute_commands",
+    "read_repository"
+  ],
+  "stop_conditions": [
+    "Stop when required input is missing, when the command cannot run without changing existing behavior, or when a claimed capability is unavailable."
+  ],
+  "tool_free_mode": {
+    "available": true,
+    "behavior": "Provide the decision, artifact template, and exact unavailable capability; never claim a tool action occurred.",
+    "unavailable_statuses": [
+      "NOT_AVAILABLE",
+      "NOT_CONFIGURED",
+      "NOT_RUN",
+      "STALE",
+      "ERROR"
+    ]
+  },
+  "handoff_to": [
+    "hyv-rewrite-prompt",
+    "hyv-prepare-rewrite"
+  ]
+}

package/skills/hyv-analyze/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hyv Analyze"
+  short_description: "Run separate VoiceDNA and AI Editor checks plus a non-scoring Unicode hygiene inspection against a draft."
+  default_prompt: "Use $hyv-analyze to run separate voicedna and ai editor checks plus a non-scoring unicode hygiene inspection against a draft."

package/skills/hyv-apply-hidden-text-policy/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: hyv-apply-hidden-text-policy
+description: Apply only explicitly approved minimal hidden-text removals and return hashes, exact changes, and remaining findings.
+---
+
+# hyv-apply-hidden-text-policy
+
+Apply only explicitly approved minimal hidden-text removals and return hashes, exact changes, and remaining review findings. The output must differ from the input path. This never invents removals beyond the approved policy.
+
+## Usage
+
+```text
+hyv apply-hidden-text-policy draft.md policy.json output.md
+```
+
+## Behavior
+
+- Deterministic and local-first: this command never calls a provider and never sends drafts, samples, profiles, or telemetry to a service.
+- Commands that write use an explicit output path. Confirm that path before running the command.
+- This agent describes how to invoke the command and what it returns. It does not change command behavior or exit codes.
+
+## Handoff
+
+Run `hyv apply-hidden-text-policy` directly to execute the operation. Follow-on agents: hyv-final-check.

package/skills/hyv-apply-hidden-text-policy/agent.json

@@ -0,0 +1,49 @@
+{
+  "schema_version": "1.0.0",
+  "id": "hyv-apply-hidden-text-policy",
+  "title": "hyv-apply-hidden-text-policy",
+  "description": "Apply only explicitly approved minimal hidden-text removals and return hashes, exact changes, and remaining findings.",
+  "instruction_file": "SKILL.md",
+  "role": "Hidden-text editor",
+  "workflow_phase": "edit",
+  "input": {
+    "required": [
+      "draft path",
+      "policy path",
+      "output path"
+    ],
+    "optional": []
+  },
+  "output": {
+    "required": [
+      "written output.md",
+      "change report"
+    ],
+    "optional": []
+  },
+  "evidence_requirements": [
+    "Report only the deterministic result the command returns; never invent a model or provider call that did not occur."
+  ],
+  "permissions": [
+    "execute_commands",
+    "read_repository",
+    "write_repository"
+  ],
+  "stop_conditions": [
+    "Stop when required input is missing, when the command cannot run without changing existing behavior, or when a claimed capability is unavailable."
+  ],
+  "tool_free_mode": {
+    "available": true,
+    "behavior": "Provide the decision, artifact template, and exact unavailable capability; never claim a tool action occurred.",
+    "unavailable_statuses": [
+      "NOT_AVAILABLE",
+      "NOT_CONFIGURED",
+      "NOT_RUN",
+      "STALE",
+      "ERROR"
+    ]
+  },
+  "handoff_to": [
+    "hyv-final-check"
+  ]
+}

package/skills/hyv-apply-hidden-text-policy/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hyv Apply Hidden Text Policy"
+  short_description: "Apply only explicitly approved minimal hidden-text removals and return hashes, exact changes, and remaining findings."
+  default_prompt: "Use $hyv-apply-hidden-text-policy to apply only explicitly approved minimal hidden-text removals and return hashes, exact changes, and remaining findings."

package/skills/hyv-apply-rebuild/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: hyv-apply-rebuild
+description: Validate and evaluate a whole-document rebuild response against a prepared authorized rebuild task.
+---
+
+# hyv-apply-rebuild
+
+Validate and evaluate a whole-document rebuild response against a prepared authorized rebuild task. Capability input requires host-guaranteed sensitive-input redaction. It never calls a provider.
+
+## Usage
+
+```text
+hyv apply-rebuild task.json response.json profile.json (--capability-stdin|--capability-file path)
+```
+
+## Behavior
+
+- Deterministic and local-first: this command never calls a provider and never sends drafts, samples, profiles, or telemetry to a service.
+- Commands that write use an explicit output path. Confirm that path before running the command.
+- This agent describes how to invoke the command and what it returns. It does not change command behavior or exit codes.
+
+## Handoff
+
+Run `hyv apply-rebuild` directly to execute the operation. Follow-on agents: hyv-verify, hyv-lifecycle.