hafez 1.2.0 → 1.3.0

package/dist/cli/commands.js

@@ -1,45 +1,56 @@
 // src/cli/commands.ts
-import { z } from 'zod';
 import { readFileSync } from 'fs';
+import { parseArgs, splitList, str, UsageError } from './args.js';
 import { HafezError } from '../types.js';
-import { ENTITY_TYPES, ENTITY_STATUSES, SESSION_LOG_TYPES, CONFIDENCE_LEVELS, VALID_SUBTYPES, } from '../contracts.js';
+import { BatchOperationSchema } from '../batch-ops.js';
 import { formatBatchError } from './batch-errors.js';
 import { parseDigestInput, digest } from '../digest.js';
 import { formatEntityHeader, formatKnowledgeHeader, formatQueryTable, formatKnowledgeTable, formatSearchResults, formatValidation, formatStats, formatChangelog } from './format.js';
 function jsonOut(data) {
     return JSON.stringify(data, null, 2);
 }
+const READ_USAGE = 'Usage: hafez read <slug> [--depth frontmatter|summary|full]';
+const READ_FLAGS = { depth: 'string' };
 export async function cmdRead(os, args, opts = {}) {
-    const slug = args[0];
+    const { flags, positionals } = parseArgs(args, READ_FLAGS, READ_USAGE);
+    const slug = positionals[0];
     if (!slug)
-        throw new Error('Usage: hafez read <slug> [--depth frontmatter|summary|full]');
-    const depth = (getFlag(args, '--depth') ?? 'summary');
+        throw new UsageError(READ_USAGE);
+    const depth = (str(flags.depth) ?? 'summary');
     const result = await os.read(slug, depth);
     if (opts.json)
         return jsonOut(result);
     const fm = result.frontmatter;
-    if ('type' in fm)
+    if (result.kind === 'entity')
         return formatEntityHeader(fm, result.body);
     return formatKnowledgeHeader(fm, result.body);
 }
+const QUERY_USAGE = 'Usage: hafez query [--kind entity|knowledge|all] [--filter ...] [--type t] [--parent slug] [--related-to slug] [--domain d] [--confidence c] [--subtype s] [--tag t] [--since d] [--before d] [--created-since d] [--created-before d] [--sort-by f] [--sort-order asc|desc] [--limit n] [--offset n]';
+const QUERY_FLAGS = {
+    kind: 'string', filter: 'string', type: 'string', parent: 'string', 'related-to': 'string',
+    domain: 'string', confidence: 'string', subtype: 'string', tag: 'string',
+    since: 'string', before: 'string', 'created-since': 'string', 'created-before': 'string',
+    'sort-by': 'string', 'sort-order': 'string', limit: 'string', offset: 'string',
+};
 export async function cmdQuery(os, args, opts = {}) {
-    const kind = getFlag(args, '--kind') ?? 'entity';
-    const filter = (getFlag(args, '--filter') ?? 'active');
-    const type = getFlag(args, '--type');
-    const parent = getFlag(args, '--parent');
-    const relatedTo = getFlag(args, '--related-to');
-    const domain = getFlag(args, '--domain');
-    const confidence = getFlag(args, '--confidence');
-    const since = getFlag(args, '--since');
-    const before = getFlag(args, '--before');
-    const createdSince = getFlag(args, '--created-since');
-    const createdBefore = getFlag(args, '--created-before');
-    const tagRaw = getFlag(args, '--tag');
+    const { flags } = parseArgs(args, QUERY_FLAGS, QUERY_USAGE);
+    const kind = str(flags.kind) ?? 'entity';
+    const filter = (str(flags.filter) ?? 'active');
+    const type = str(flags.type);
+    const parent = str(flags.parent);
+    const relatedTo = str(flags['related-to']);
+    const domain = str(flags.domain);
+    const confidence = str(flags.confidence);
+    const since = str(flags.since);
+    const before = str(flags.before);
+    const createdSince = str(flags['created-since']);
+    const createdBefore = str(flags['created-before']);
+    const tagRaw = str(flags.tag);
     const tags = tagRaw ? tagRaw.split(',').map(t => t.trim()).filter(Boolean) : undefined;
-    const sortBy = getFlag(args, '--sort-by');
-    const sortOrder = getFlag(args, '--sort-order');
-    const limitRaw = getFlag(args, '--limit');
-    const offsetRaw = getFlag(args, '--offset');
+    const sortBy = str(flags['sort-by']);
+    const sortOrder = str(flags['sort-order']);
+    const limitRaw = str(flags.limit);
+    const offsetRaw = str(flags.offset);
     const limit = limitRaw != null ? parseInt(limitRaw, 10) : undefined;
     const offset = offsetRaw != null ? parseInt(offsetRaw, 10) : undefined;
     const sortOpts = { sort_by: sortBy, sort_order: sortOrder, limit, offset };
@@ -49,8 +60,8 @@ export async function cmdQuery(os, args, opts = {}) {
         if (opts.json)
             return jsonOut(result);
         const { items: results, total } = result;
-        const entities = results.filter((r) => 'type' in r);
-        const knowledge = results.filter((r) => 'confidence' in r);
+        const entities = results.filter(r => r.kind === 'entity');
+        const knowledge = results.filter(r => r.kind === 'knowledge');
         const sections = [];
         if (entities.length > 0)
             sections.push('## Entities\n\n' + formatQueryTable(entities, total));
@@ -62,7 +73,7 @@ export async function cmdQuery(os, args, opts = {}) {
     // --kind knowledge: query knowledge only
     // Note: time flags only apply to entity queries.
     if (kind === 'knowledge') {
-        const subtype = getFlag(args, '--subtype');
+        const subtype = str(flags.subtype);
         const kOpts = { domain: domain ?? undefined, confidence, subtype, tags, ...sortOpts };
         const result = await os.query_knowledge(kOpts);
         if (opts.json)
@@ -92,127 +103,149 @@ export async function cmdQuery(os, args, opts = {}) {
         return jsonOut(result);
     return formatQueryTable(result.items, result.total);
 }
+const SEARCH_USAGE = 'Usage: hafez search <terms> [--kind entity|knowledge|all]';
+const SEARCH_FLAGS = { kind: 'string' };
 export async function cmdSearch(os, args, opts = {}) {
-    const terms = positionalArgs(args).join(' ');
+    const { flags, positionals } = parseArgs(args, SEARCH_FLAGS, SEARCH_USAGE);
+    const terms = positionals.join(' ');
     if (!terms)
-        throw new Error('Usage: hafez search <terms> [--kind entity|knowledge|all]');
-    const kind = (getFlag(args, '--kind') ?? 'all');
+        throw new UsageError(SEARCH_USAGE);
+    const kind = (str(flags.kind) ?? 'all');
     const results = await os.search(terms, kind);
     if (opts.json)
         return jsonOut(results);
     return formatSearchResults(results);
 }
+const CREATE_USAGE = 'Usage: hafez create <entity|knowledge> <name> [options]';
+const CREATE_FLAGS = {
+    type: 'string', purpose: 'string', description: 'string', resource: 'string',
+    domain: 'string', parent: 'string', related: 'string', tags: 'string',
+    brief: 'string', 'add-action': 'string',
+    subtype: 'string', synthesis: 'string', insight: 'string',
+};
 export async function cmdCreate(os, args, opts = {}) {
-    const kind = args[0];
+    const { flags, positionals } = parseArgs(args, CREATE_FLAGS, CREATE_USAGE);
+    const kind = positionals[0];
     if (!kind)
-        throw new Error('Usage: hafez create <entity|knowledge> <name> [options]');
-    const name = positionalArgs(args.slice(1)).join(' ');
+        throw new UsageError(CREATE_USAGE);
+    const name = positionals.slice(1).join(' ');
     if (!name)
-        throw new Error(`Usage: hafez create ${kind} <name> [options]`);
+        throw new UsageError(`Usage: hafez create ${kind} <name> [options]`);
     if (kind === 'entity') {
-        const type = getFlag(args, '--type');
+        const type = str(flags.type);
         if (!type)
-            throw new Error('--type is required for entity creation');
+            throw new UsageError('--type is required for entity creation');
         const slug = await os.create('entity', name, {
             type,
-            purpose: getFlag(args, '--purpose'),
-            description: getFlag(args, '--description'),
-            resource: getFlag(args, '--resource'),
-            domain: getFlag(args, '--domain')?.split(',').map(d => d.trim()),
-            parent: getFlag(args, '--parent'),
-            related: getFlag(args, '--related')?.split(','),
-            tags: getFlag(args, '--tags')?.split(','),
-            brief: getFlag(args, '--brief'),
-            add_action: getFlag(args, '--add-action'),
+            purpose: str(flags.purpose),
+            description: str(flags.description),
+            resource: str(flags.resource),
+            domain: splitList(flags.domain),
+            parent: str(flags.parent),
+            related: str(flags.related)?.split(','),
+            tags: str(flags.tags)?.split(','),
+            brief: str(flags.brief),
+            add_action: str(flags['add-action']),
         });
         return opts.json ? jsonOut({ slug }) : slug;
     }
     if (kind === 'knowledge') {
         const slug = await os.create('knowledge', name, {
-            subtype: getFlag(args, '--subtype'),
-            synthesis: getFlag(args, '--synthesis') ?? getFlag(args, '--insight'),
-            description: getFlag(args, '--description'),
-            domain: getFlag(args, '--domain')?.split(','),
-            related: getFlag(args, '--related')?.split(','),
-            tags: getFlag(args, '--tags')?.split(','),
+            subtype: str(flags.subtype),
+            synthesis: str(flags.synthesis) ?? str(flags.insight),
+            description: str(flags.description),
+            domain: str(flags.domain)?.split(','),
+            related: str(flags.related)?.split(','),
+            tags: str(flags.tags)?.split(','),
         });
         return opts.json ? jsonOut({ slug }) : slug;
     }
-    throw new Error(`Unknown kind: ${kind}. Use entity or knowledge.`);
+    throw new UsageError(`Unknown kind: ${kind}. Use entity or knowledge.`);
 }
+const UPDATE_USAGE = 'Usage: hafez update <slug> [--brief text] [--description text] [--resource uri] [--add-action text] [--complete-action text] [--remove-action text] [--clear-actions] [--status s] [--log "type: summary"]';
+const UPDATE_FLAGS = {
+    status: 'string', 'current-state': 'string', brief: 'string',
+    'add-action': 'string', 'complete-action': 'string', 'remove-action': 'string',
+    'clear-actions': 'boolean', log: 'string', agent: 'string',
+    description: 'string', resource: 'string', domain: 'string', confidence: 'string',
+    tags: 'string', related: 'string', insight: 'string', synthesis: 'string',
+    'add-evidence': 'string', 'add-source': 'string',
+    // Removed flag, declared so it fails with guidance instead of a generic
+    // unknown-flag error: older installed skills/scripts still pass it, and
+    // "Updated <slug>" with the action discarded is a false success.
+    'next-action': 'string',
+};
 export async function cmdUpdate(os, args, opts = {}) {
-    const slug = args[0];
+    const { flags, positionals } = parseArgs(args, UPDATE_FLAGS, UPDATE_USAGE);
+    const slug = positionals[0];
     if (!slug)
-        throw new Error('Usage: hafez update <slug> [--brief text] [--description text] [--resource uri] [--add-action text] [--complete-action text] [--remove-action text] [--clear-actions] [--status s] [--log "type: summary"]');
+        throw new UsageError(UPDATE_USAGE);
+    if (flags['next-action'] !== undefined) {
+        throw new UsageError('--next-action was removed in v1.0.2. Use --add-action (and --clear-actions) instead.');
+    }
     const fields = {};
-    const status = getFlag(args, '--status');
+    const status = str(flags.status);
     if (status)
         fields.status = status;
-    // Removed flag must fail loudly, not silently drop the value: older
-    // installed skills/scripts still pass it, and "Updated <slug>" with the
-    // action discarded is a false success.
-    if (args.includes('--next-action')) {
-        throw new Error('--next-action was removed in v1.0.2. Use --add-action (and --clear-actions) instead.');
-    }
-    const currentState = getFlag(args, '--current-state');
+    const currentState = str(flags['current-state']);
     if (currentState)
         fields.current_state = currentState;
     // Brief
-    const brief = getFlag(args, '--brief');
+    const brief = str(flags.brief);
     if (brief !== undefined) {
         fields.brief = brief === '' ? null : brief;
     }
     // Next Actions
-    const addAction = getFlag(args, '--add-action');
+    const addAction = str(flags['add-action']);
     if (addAction)
         fields.add_action = addAction;
-    const completeAction = getFlag(args, '--complete-action');
+    const completeAction = str(flags['complete-action']);
     if (completeAction)
         fields.complete_action = completeAction;
-    const removeAction = getFlag(args, '--remove-action');
+    const removeAction = str(flags['remove-action']);
     if (removeAction)
         fields.remove_action = removeAction;
-    if (args.includes('--clear-actions'))
+    if (flags['clear-actions'])
         fields.clear_actions = true;
-    const log = getFlag(args, '--log');
+    const log = str(flags.log);
     if (log) {
         const colonIdx = log.indexOf(':');
         if (colonIdx === -1)
-            throw new Error('--log format: "type: summary". Types: progress, decision, blocker, research');
+            throw new UsageError('--log format: "type: summary". Types: progress, decision, blocker, research');
         const type = log.slice(0, colonIdx).trim();
         const summary = log.slice(colonIdx + 1).trim();
-        const agent = getFlag(args, '--agent') ?? 'claude';
+        const agent = str(flags.agent) ?? 'claude';
         fields.session_log = { type, summary, agent };
     }
     // Shared metadata (entity + knowledge)
-    const description = getFlag(args, '--description');
+    const description = str(flags.description);
     if (description !== undefined)
         fields.description = description;
-    const resource = getFlag(args, '--resource');
+    const resource = str(flags.resource);
     if (resource !== undefined)
         fields.resource = resource;
-    const domainRaw = getFlag(args, '--domain');
-    if (domainRaw)
-        fields.domain = domainRaw.split(',').map((d) => d.trim());
-    const conf = getFlag(args, '--confidence');
+    const domain = splitList(flags.domain);
+    if (domain)
+        fields.domain = domain;
+    const conf = str(flags.confidence);
     if (conf)
         fields.confidence = conf;
-    const tagsRaw = getFlag(args, '--tags');
-    if (tagsRaw)
-        fields.tags = tagsRaw.split(',').map((t) => t.trim());
-    const relatedRaw = getFlag(args, '--related');
-    if (relatedRaw)
-        fields.related = relatedRaw.split(',').map((r) => r.trim());
-    const insight = getFlag(args, '--insight');
+    const tags = splitList(flags.tags);
+    if (tags)
+        fields.tags = tags;
+    const related = splitList(flags.related);
+    if (related)
+        fields.related = related;
+    const insight = str(flags.insight);
     if (insight)
         fields.synthesis = insight;
-    const synthesis = getFlag(args, '--synthesis');
+    const synthesis = str(flags.synthesis);
     if (synthesis)
         fields.synthesis = synthesis;
-    const addEvidence = getFlag(args, '--add-evidence');
+    const addEvidence = str(flags['add-evidence']);
     if (addEvidence)
         fields.add_evidence = addEvidence;
-    const addSource = getFlag(args, '--add-source');
+    const addSource = str(flags['add-source']);
     if (addSource)
         fields.add_source = addSource;
     const result = await os.update(slug, fields);
@@ -224,23 +257,17 @@ export async function cmdUpdate(os, args, opts = {}) {
     }
     return lines.join('\n');
 }
+const LINK_FLAGS = { relation: 'string' };
 function parseLinkArgs(args, verb) {
-    const relation = getFlag(args, '--relation');
-    // After getFlag the relation value is still at its original positional slot
-    // (getFlag does NOT splice), so strip it manually before reading positionals.
-    const positionals = args.filter((a, i) => {
-        if (a === '--relation')
-            return false;
-        if (i > 0 && args[i - 1] === '--relation')
-            return false;
-        return !a.startsWith('--');
-    });
+    const usage = `Usage: hafez ${verb} <slug> <target> --relation <parent|related>`;
+    const { flags, positionals } = parseArgs(args, LINK_FLAGS, usage);
+    const relation = str(flags.relation);
     const [slug, target] = positionals;
     if (!slug || !target || !relation) {
-        throw new Error(`Usage: hafez ${verb} <slug> <target> --relation <parent|related>`);
+        throw new UsageError(usage);
     }
     if (!['parent', 'related'].includes(relation)) {
-        throw new Error(`Invalid relation: ${relation}. Must be parent or related.`);
+        throw new UsageError(`Invalid relation: ${relation}. Must be parent or related.`);
     }
     return { slug, target, relation };
 }
@@ -255,22 +282,24 @@ export async function cmdUnlink(os, args, opts = {}) {
     return opts.json ? jsonOut({ slug, target, relation }) : `Unlinked ${slug} — ${target} (${relation})`;
 }
 /** Top-level capture command — aligns the CLI verb with the batch op name. */
+const CAPTURE_USAGE = 'Usage: hafez capture <name> [--notes "text"]';
+const CAPTURE_FLAGS = { notes: 'string' };
 export async function cmdCapture(os, args, opts = {}) {
-    const name = positionalArgs(args).join(' ');
+    const { flags, positionals } = parseArgs(args, CAPTURE_FLAGS, CAPTURE_USAGE);
+    const name = positionals.join(' ');
     if (!name)
-        throw new Error('Usage: hafez capture <name> [--notes "text"]');
-    const notes = getFlag(args, '--notes');
+        throw new UsageError(CAPTURE_USAGE);
+    const notes = str(flags.notes);
     const slug = await os.capture(name, notes);
     return opts.json ? jsonOut({ slug }) : slug;
 }
+const PROMOTE_USAGE = 'Usage: hafez promote <slug> <entity|project|knowledge>';
 export async function cmdPromote(os, args, opts = {}) {
-    const slug = args[0];
-    const target = args[1];
+    const { positionals } = parseArgs(args, {}, PROMOTE_USAGE);
+    const [slug, target] = positionals;
     if (!slug || !target)
-        throw new Error('Usage: hafez promote <slug> <entity|project|knowledge>');
-    if (!['entity', 'project', 'knowledge'].includes(target)) {
-        throw new Error(`Invalid target: ${target}. Must be entity, project, or knowledge.`);
-    }
+        throw new UsageError(PROMOTE_USAGE);
+    // Target validity is core's rule (contract canPromoteTo) — no CLI re-check.
     await os.promote(slug, target);
     if (opts.json)
         return jsonOut({ slug, target });
@@ -304,10 +333,13 @@ export async function cmdStats(os, _args, opts = {}) {
         return jsonOut(stats);
     return formatStats(stats);
 }
+const CHANGELOG_USAGE = 'Usage: hafez changelog --since <date|relative>\nExamples: --since 2026-03-20, --since 7.days.ago, --since 1.week.ago';
+const CHANGELOG_FLAGS = { since: 'string' };
 export async function cmdChangelog(os, args, opts = {}) {
-    const since = getFlag(args, '--since');
+    const { flags } = parseArgs(args, CHANGELOG_FLAGS, CHANGELOG_USAGE);
+    const since = str(flags.since);
     if (!since)
-        throw new Error('Usage: hafez changelog --since <date|relative>\nExamples: --since 2026-03-20, --since 7.days.ago, --since 1.week.ago');
+        throw new UsageError(CHANGELOG_USAGE);
     const entries = await os.changelog(since);
     if (opts.json)
         return jsonOut(entries);
@@ -315,127 +347,11 @@ export async function cmdChangelog(os, args, opts = {}) {
 }
 // --- Batch ---
 // All enums are built from contracts.ts tuples so help-renderer, file validators,
-// and CLI-input validator share a single source of truth. cli-schema-parity.test.ts
-// enforces this on every build.
+// and CLI-input validator share a single source of truth — drift is structurally
+// impossible (the Op Spec table in batch-ops.ts is the only consumer).
 // Every z.object(...) is .strict() — unknown keys become `unrecognized_keys` issues
 // (not silently dropped), which is load-bearing for the error-formatter's did-you-mean
 // hints and for catching typos like `{"kind": "parent"}` on a link op.
-export const SessionLogSchema = z.object({
-    type: z.enum([...SESSION_LOG_TYPES]),
-    summary: z.string(),
-    body: z.string().optional(),
-    agent: z.string(),
-}).strict();
-export const UpdateFieldsSchema = z.object({
-    status: z.enum([...ENTITY_STATUSES]).optional(),
-    current_state: z.string().optional(),
-    session_log: SessionLogSchema.optional(),
-    brief: z.string().nullable().optional(),
-    add_action: z.string().optional(),
-    add_actions: z.array(z.string()).optional(),
-    complete_action: z.string().optional(),
-    remove_action: z.string().optional(),
-    clear_actions: z.boolean().optional(),
-    // Knowledge metadata
-    description: z.string().nullable().optional(),
-    resource: z.string().nullable().optional(),
-    domain: z.array(z.string()).optional(),
-    confidence: z.enum([...CONFIDENCE_LEVELS]).optional(),
-    tags: z.array(z.string()).optional(),
-    related: z.array(z.string()).optional(),
-    synthesis: z.string().optional(),
-    insight: z.string().optional(), // alias for synthesis (normalized in parseBatchInput)
-    add_evidence: z.string().optional(),
-    add_source: z.string().optional(),
-}).strict();
-const CreateEntityFieldsSchema = z.object({
-    type: z.enum([...ENTITY_TYPES]),
-    purpose: z.string().optional(),
-    description: z.string().optional(),
-    resource: z.string().optional(),
-    domain: z.array(z.string()).optional(),
-    parent: z.string().optional(),
-    related: z.array(z.string()).optional(),
-    tags: z.array(z.string()).optional(),
-    brief: z.string().optional(),
-    add_action: z.string().optional(),
-    add_actions: z.array(z.string()).optional(),
-}).strict();
-const CreateKnowledgeFieldsSchema = z.object({
-    subtype: z.enum([...VALID_SUBTYPES]).optional(),
-    synthesis: z.string().optional(),
-    insight: z.string().optional(),
-    description: z.string().optional(),
-    domain: z.array(z.string()).optional(),
-    related: z.array(z.string()).optional(),
-    tags: z.array(z.string()).optional(),
-    'session-date': z.string().optional(),
-}).strict();
-const CreateSessionFieldsSchema = z.object({
-    synthesis: z.string().optional(),
-    insight: z.string().optional(),
-    related: z.array(z.string()).optional(),
-    'session-date': z.string().optional(),
-}).strict();
-const CreateEntityBranch = z.object({
-    op: z.literal('create'),
-    kind: z.literal('entity'),
-    name: z.string(),
-    fields: CreateEntityFieldsSchema,
-}).strict();
-const CreateKnowledgeBranch = z.object({
-    op: z.literal('create'),
-    kind: z.literal('knowledge'),
-    name: z.string(),
-    fields: CreateKnowledgeFieldsSchema.optional(),
-}).strict();
-const CreateSessionBranch = z.object({
-    op: z.literal('create'),
-    kind: z.literal('session'),
-    name: z.string(),
-    fields: CreateSessionFieldsSchema.optional(),
-}).strict();
-// Nested discriminated union: outer on `op`, inner on `kind` for create branch.
-// A flat `discriminatedUnion('op', [...])` cannot work because three branches share
-// op=create — Zod requires unique discriminator values per branch and throws at
-// schema construction time if violated.
-const CreateBranch = z.discriminatedUnion('kind', [
-    CreateEntityBranch,
-    CreateKnowledgeBranch,
-    CreateSessionBranch,
-]);
-export const BatchOperationSchema = z.discriminatedUnion('op', [
-    z.object({
-        op: z.literal('update'),
-        slug: z.string(),
-        fields: UpdateFieldsSchema,
-    }).strict(),
-    // create is a nested discriminatedUnion on `kind` — see CreateBranch above.
-    // discriminatedUnion accepts a ZodDiscriminatedUnion as a branch via option-flattening.
-    CreateBranch,
-    z.object({
-        op: z.literal('capture'),
-        name: z.string(),
-        notes: z.string().optional(),
-    }).strict(),
-    z.object({
-        op: z.literal('link'),
-        slug: z.string(),
-        target: z.string(),
-        relation: z.enum(['parent', 'related']),
-    }).strict(),
-    z.object({
-        op: z.literal('unlink'),
-        slug: z.string(),
-        target: z.string(),
-        relation: z.enum(['parent', 'related']),
-    }).strict(),
-    z.object({
-        op: z.literal('promote'),
-        slug: z.string(),
-        target: z.enum(['entity', 'project', 'knowledge']),
-    }).strict(),
-]);
 export function parseBatchInput(json) {
     let parsed;
     try {
@@ -486,7 +402,7 @@ export function parseBatchInput(json) {
         operations.push(op);
     }
     if (failureBlocks.length > 0) {
-        const header = `Batch contains ${failureBlocks.length} invalid operation${failureBlocks.length === 1 ? '' : 's'} (0 of ${parsed.length} applied, batch aborted):`;
+        const header = `Batch failed validation: ${failureBlocks.length} invalid operation${failureBlocks.length === 1 ? '' : 's'} (0 of ${parsed.length} applied)`;
         throw new HafezError('VALIDATION_FAILED', header, failureBlocks);
     }
     return operations;
@@ -517,9 +433,12 @@ function readStdin() {
         process.stdin.on('error', reject);
     });
 }
+const BATCH_USAGE = "Usage: hafez batch [--dry-run] [--file payload.json]  (or pipe JSON to stdin)";
+const BATCH_FLAGS = { 'dry-run': 'boolean', file: 'string' };
 export async function cmdBatch(os, args, opts = {}) {
-    const dryRun = args.includes('--dry-run');
-    const file = getFlag(args, '--file');
+    const { flags } = parseArgs(args, BATCH_FLAGS, BATCH_USAGE);
+    const dryRun = flags['dry-run'] === true;
+    const file = str(flags.file);
     const input = file ? readPayloadFile(file) : await readStdin();
     if (!input.trim()) {
         throw new HafezError('VALIDATION_FAILED', 'No input received. Pipe JSON array to stdin (echo \'[...]\' | hafez batch) or pass --file payload.json');
@@ -558,11 +477,14 @@ export async function cmdBatch(os, args, opts = {}) {
         output += ` (created: ${created.join(', ')})`;
     return output;
 }
+const DIGEST_USAGE = 'Usage: hafez digest [--file summary.json]  (or pipe JSON to stdin)';
+const DIGEST_FLAGS = { file: 'string' };
 export async function cmdDigest(os, args, _opts = {}) {
-    const file = getFlag(args, '--file');
+    const { flags } = parseArgs(args, DIGEST_FLAGS, DIGEST_USAGE);
+    const file = str(flags.file);
     const raw = file ? readPayloadFile(file) : await readStdin();
     if (!raw.trim()) {
-        throw new Error('No input received. Pipe JSON object to stdin (echo \'{"entities_touched":...}\' | hafez digest) or pass --file summary.json');
+        throw new UsageError('No input received. Pipe JSON object to stdin (echo \'{"entities_touched":...}\' | hafez digest) or pass --file summary.json');
     }
     // Parse JSON
     let parsed;
@@ -570,12 +492,12 @@ export async function cmdDigest(os, args, _opts = {}) {
         parsed = JSON.parse(raw);
     }
     catch {
-        throw new Error('Invalid JSON on stdin: ' + (raw.slice(0, 80)));
+        throw new HafezError('VALIDATION_FAILED', 'Invalid JSON on stdin: ' + (raw.slice(0, 80)));
     }
     const result = parseDigestInput(parsed);
     if (!result.success) {
         const fields = result.error.issues.map(i => i.path.join('.')).join(', ');
-        throw new Error(`Invalid digest input — missing or invalid fields: ${fields}`);
+        throw new HafezError('VALIDATION_FAILED', `Invalid digest input — missing or invalid fields: ${fields}`);
     }
     // Warn about unknown fields
     if (result.unknownFields.length > 0) {
@@ -592,23 +514,3 @@ export async function cmdDigest(os, args, _opts = {}) {
     const ops = digest(result.data, existingSlugs);
     return JSON.stringify(ops, null, 2);
 }
-// --- Arg helpers ---
-function getFlag(args, flag) {
-    const idx = args.indexOf(flag);
-    if (idx === -1)
-        return undefined;
-    return args[idx + 1];
-}
-/** Extract positional args by skipping --flag value pairs */
-function positionalArgs(args) {
-    const result = [];
-    for (let i = 0; i < args.length; i++) {
-        if (args[i].startsWith('--')) {
-            i++; // skip the flag's value too
-        }
-        else {
-            result.push(args[i]);
-        }
-    }
-    return result;
-}

package/dist/cli/help-agent.d.ts

@@ -1,6 +1 @@
-/**
- * Render the full prompt-gate output. Token budget: 1500-3000 tokens when
- * measured as char/3.5. The drift test in tests/cli-help-agent.test.ts
- * enforces the ceiling.
- */
 export declare function renderAgentHelp(): string;

package/dist/cli/help-agent.js

@@ -5,12 +5,13 @@
 // session and then produce valid batch JSON on first try.
 //
 // Hand-written sections: Preamble + Hard rules (prose, free-form).
-// Generated sections (wrapped in <!-- SECTION:name --> markers so the drift
-// test can parse them): op-catalog, critical-enums, batch-examples, digest.
+// Generated sections (wrapped in <!-- SECTION:name --> markers so tests can
+// parse them): op-catalog, critical-enums, batch-examples, digest.
 //
-// If the generated sections drift from the Zod schema, the drift test fails
-// loudly. Do NOT enumerate enum values inside the preamble or hard rules —
-// those come from schema-introspect.ts.
+// Generated sections derive from the Op Spec table (batch-ops.ts via
+// schema-introspect.ts), so they cannot drift from the Zod schemas. Do NOT
+// enumerate enum values inside the preamble or hard rules — those come from
+// schema-introspect.ts.
 import { listOps, getEnumValues, getOpExample, getOpSchema } from './schema-introspect.js';
 const PREAMBLE = `# Hafez — Agent Prompt Gate
 
@@ -155,6 +156,18 @@ const FOOTER = `## Lookup pointers
  * measured as char/3.5. The drift test in tests/cli-help-agent.test.ts
  * enforces the ceiling.
  */
+const EXIT_CODES_SECTION = `## Exit codes
+
+| code | meaning |
+|------|---------|
+| 0 | success |
+| 1 | not found / unknown error |
+| 2 | validation or usage error (bad flags, bad payload, core rejected the write) |
+| 3 | git push failed — the write IS committed locally |
+| 4 | write succeeded but the auto-sync after it failed |
+| 5 | slug already exists |
+| 6 | git commit failed — nothing was written to history |
+| 7 | vault locked by another hafez process — retry when it finishes |`;
 export function renderAgentHelp() {
     return [
         PREAMBLE,
@@ -166,6 +179,8 @@ export function renderAgentHelp() {
         '',
         renderDigestSection(),
         '',
+        EXIT_CODES_SECTION,
+        '',
         FOOTER,
     ].join('\n');
 }