@kynetic-ai/spec 0.1.2 → 0.4.0

package/dist/cli/commands/meta.js

@@ -7,54 +7,64 @@
  * AC-agent-1: kspec meta agents outputs table
  * AC-agent-2: kspec meta agents --json outputs JSON
  */
-import chalk from 'chalk';
-import Table from 'cli-table3';
-import { ulid } from 'ulid';
-import { initContext, loadMetaContext, getMetaStats, createObservation, saveObservation, saveMetaItem, deleteMetaItem, createTask, saveTask, loadAllTasks, loadAllItems, ReferenceIndex, loadSessionContext, saveSessionContext, loadInboxItems, findInboxItemByRef, deleteInboxItem, } from '../../parser/index.js';
-import { output, error, success, isJsonMode } from '../output.js';
-import { errors } from '../../strings/errors.js';
-import { commitIfShadow } from '../../parser/shadow.js';
-import { EXIT_CODES } from '../exit-codes.js';
+import chalk from "chalk";
+import Table from "cli-table3";
+import { ulid } from "ulid";
+import { markMutating } from "../command-annotations.js";
+import { createObservation, createTask, deleteInboxItem, deleteMetaItem, findInboxItemByRef, getMetaStats, initContext, loadAllItems, loadAllTasks, loadInboxItems, loadMetaContext, loadSessionContext, ReferenceIndex, resolveMetaRef, saveMetaItem, saveObservation, saveSessionContext, saveTask, } from "../../parser/index.js";
+import { commitIfShadow } from "../../parser/shadow.js";
+import { normalizeRefInput } from "../../schema/index.js";
+import { z } from "zod";
+import { WorkflowStepSchema, } from "../../schema/index.js";
+import { errors } from "../../strings/errors.js";
+import { executeBatchOperation, formatBatchOutput } from "../batch.js";
+import { EXIT_CODES } from "../exit-codes.js";
+import { error, isJsonMode, output, success } from "../output.js";
+import { parseTagsArray } from "../parse-utils.js";
+import { parseIntOption } from "../validators.js";
 /**
- * Resolve a meta reference to its ULID
- * Handles semantic IDs (agent.id, workflow.id, convention.domain) and ULID prefixes
+ * Resolve a meta reference to its ULID and type.
+ * Wrapper around resolveMetaRef for backward compatibility with existing call sites.
+ * AC: @skill-meta-integration ac-4 - skills included in resolution
  */
 function resolveMetaRefToUlid(ref, metaCtx) {
-    const normalizedRef = ref.startsWith('@') ? ref.substring(1) : ref;
-    // Check agents
-    const agent = (metaCtx.agents || []).find((a) => a.id === normalizedRef || a._ulid.startsWith(normalizedRef));
-    if (agent)
-        return { ulid: agent._ulid, type: 'agent' };
-    // Check workflows
-    const workflow = (metaCtx.workflows || []).find((w) => w.id === normalizedRef || w._ulid.startsWith(normalizedRef));
-    if (workflow)
-        return { ulid: workflow._ulid, type: 'workflow' };
-    // Check conventions
-    const convention = (metaCtx.conventions || []).find((c) => c.domain === normalizedRef || c._ulid.startsWith(normalizedRef));
-    if (convention)
-        return { ulid: convention._ulid, type: 'convention' };
-    // Check observations
-    const observation = (metaCtx.observations || []).find((o) => o._ulid.startsWith(normalizedRef));
-    if (observation)
-        return { ulid: observation._ulid, type: 'observation' };
-    return null;
+    const result = resolveMetaRef(metaCtx, ref);
+    if (!result)
+        return null;
+    return { ulid: result.ulid, type: result.type };
+}
+/**
+ * Batch-compatible resolver for observations.
+ * Returns null instead of calling process.exit() to allow partial failure handling.
+ * AC: @trait-multi-ref-batch ac-2, ac-8 - Partial failure handling and ref resolution
+ */
+function resolveObservationRefForBatch(ref, observations) {
+    const normalizedRef = ref.startsWith("@") ? ref.substring(1) : ref;
+    const observation = observations.find((o) => o._ulid.startsWith(normalizedRef));
+    if (!observation) {
+        return { item: null, error: `Observation not found: ${ref}` };
+    }
+    return { item: observation };
 }
 /**
  * Format meta show output
+ * AC: @skill-meta-integration ac-3 - skill count included in summary
  */
 function formatMetaShow(meta) {
     const stats = getMetaStats(meta);
     if (!meta.manifest) {
-        console.log(chalk.yellow('No meta manifest found (kynetic.meta.yaml)'));
-        console.log(chalk.gray('Create one to define agents, workflows, conventions, and observations'));
+        console.log(chalk.yellow("No meta manifest found (kynetic.meta.yaml)"));
+        console.log(chalk.gray("Create one to define agents, workflows, conventions, observations, and skills"));
         return;
     }
-    console.log(chalk.bold('Meta-Spec Summary'));
-    console.log(chalk.gray('─'.repeat(40)));
+    console.log(chalk.bold("Meta-Spec Summary"));
+    console.log(chalk.gray("─".repeat(40)));
     console.log(`Agents:       ${stats.agents}`);
     console.log(`Workflows:    ${stats.workflows}`);
     console.log(`Conventions:  ${stats.conventions}`);
     console.log(`Observations: ${stats.observations} (${stats.unresolvedObservations} unresolved)`);
+    // AC: @skill-meta-integration ac-3 - include skill count
+    console.log(`Skills:       ${stats.skills}`);
 }
 /**
  * Format agents table output
@@ -62,36 +72,37 @@ function formatMetaShow(meta) {
  */
 function formatAgents(agents) {
     if (agents.length === 0) {
-        console.log(chalk.yellow('No agents defined'));
+        console.log(chalk.yellow("No agents defined"));
         return;
     }
     const table = new Table({
-        head: [chalk.bold('ID'), chalk.bold('Name'), chalk.bold('Capabilities')],
+        head: [chalk.bold("ID"), chalk.bold("Name"), chalk.bold("Capabilities")],
         style: {
             head: [],
             border: [],
         },
     });
     for (const agent of agents) {
-        table.push([
-            agent.id,
-            agent.name,
-            agent.capabilities.join(', '),
-        ]);
+        table.push([agent.id, agent.name, agent.capabilities.join(", ")]);
     }
     console.log(table.toString());
 }
 /**
  * Format workflows table output
- * AC-workflow-1: outputs table with columns: ID, Trigger, Steps (count)
+ * AC-workflow-1: outputs table with columns: ID, Trigger, Steps (count), Mode
  */
 function formatWorkflows(workflows) {
     if (workflows.length === 0) {
-        console.log(chalk.yellow('No workflows defined'));
+        console.log(chalk.yellow("No workflows defined"));
         return;
     }
     const table = new Table({
-        head: [chalk.bold('ID'), chalk.bold('Trigger'), chalk.bold('Steps')],
+        head: [
+            chalk.bold("ID"),
+            chalk.bold("Trigger"),
+            chalk.bold("Steps"),
+            chalk.bold("Mode"),
+        ],
         style: {
             head: [],
             border: [],
@@ -102,6 +113,7 @@ function formatWorkflows(workflows) {
             workflow.id,
             workflow.trigger,
             workflow.steps.length.toString(),
+            workflow.mode || "interactive",
         ]);
     }
     console.log(table.toString());
@@ -109,23 +121,32 @@ function formatWorkflows(workflows) {
 /**
  * Format workflows verbose output
  * AC-workflow-2: outputs each workflow with full step list
+ * AC: @loop-mode-workflows ac-3 (shows based_on field)
  */
 function formatWorkflowsVerbose(workflows) {
     if (workflows.length === 0) {
-        console.log(chalk.yellow('No workflows defined'));
+        console.log(chalk.yellow("No workflows defined"));
         return;
     }
     for (const workflow of workflows) {
         console.log(chalk.bold(`${workflow.id} - ${workflow.trigger}`));
+        // Show mode if it's loop (skip for interactive as it's default)
+        if (workflow.mode === "loop") {
+            console.log(chalk.cyan(`Mode: ${workflow.mode}`));
+        }
+        // AC: @loop-mode-workflows ac-3 - Show based_on reference
+        if (workflow.based_on) {
+            console.log(chalk.cyan(`Based on: ${workflow.based_on}`));
+        }
         if (workflow.description) {
             console.log(chalk.gray(workflow.description));
         }
-        console.log(chalk.gray('─'.repeat(60)));
+        console.log(chalk.gray("─".repeat(60)));
         for (const step of workflow.steps) {
             const prefix = {
-                check: chalk.yellow('[check]'),
-                action: chalk.blue('[action]'),
-                decision: chalk.magenta('[decision]'),
+                check: chalk.yellow("[check]"),
+                action: chalk.blue("[action]"),
+                decision: chalk.magenta("[decision]"),
             }[step.type];
             console.log(`${prefix} ${step.content}`);
             if (step.on_fail) {
@@ -137,7 +158,7 @@ function formatWorkflowsVerbose(workflows) {
                 }
             }
         }
-        console.log('');
+        console.log("");
     }
 }
 /**
@@ -146,11 +167,11 @@ function formatWorkflowsVerbose(workflows) {
  */
 function formatConventions(conventions) {
     if (conventions.length === 0) {
-        console.log(chalk.yellow('No conventions defined'));
+        console.log(chalk.yellow("No conventions defined"));
         return;
     }
     const table = new Table({
-        head: [chalk.bold('Domain'), chalk.bold('Rules'), chalk.bold('Validation')],
+        head: [chalk.bold("Domain"), chalk.bold("Rules"), chalk.bold("Validation")],
         style: {
             head: [],
             border: [],
@@ -160,7 +181,7 @@ function formatConventions(conventions) {
         table.push([
             convention.domain,
             convention.rules.length.toString(),
-            convention.validation ? 'yes' : 'no',
+            convention.validation ? "yes" : "no",
         ]);
     }
     console.log(table.toString());
@@ -171,20 +192,20 @@ function formatConventions(conventions) {
  */
 function formatConventionDetail(convention) {
     console.log(chalk.bold(`${convention.domain} Convention`));
-    console.log(chalk.gray('─'.repeat(60)));
-    console.log(chalk.bold('\nRules:'));
+    console.log(chalk.gray("─".repeat(60)));
+    console.log(chalk.bold("\nRules:"));
     for (const rule of convention.rules) {
         console.log(`  • ${rule}`);
     }
     if (convention.examples && convention.examples.length > 0) {
-        console.log(chalk.bold('\nExamples:'));
+        console.log(chalk.bold("\nExamples:"));
         for (const example of convention.examples) {
             console.log(chalk.green(`  ✓ ${example.good}`));
             console.log(chalk.red(`  ✗ ${example.bad}`));
         }
     }
     if (convention.validation) {
-        console.log(chalk.bold('\nValidation:'));
+        console.log(chalk.bold("\nValidation:"));
         console.log(`  Type: ${convention.validation.type}`);
         if (convention.validation.pattern) {
             console.log(`  Pattern: ${convention.validation.pattern}`);
@@ -193,39 +214,69 @@ function formatConventionDetail(convention) {
             console.log(`  Message: ${convention.validation.message}`);
         }
     }
-    console.log('');
+    console.log("");
 }
 /**
  * Format observations table output
  * AC-obs-2: outputs table with columns: ID, Type, Workflow, Created, Content (truncated)
+ * AC: @obs-list-display ac-1 - When --all flag used, show Resolved column with ✓/✗
  */
 function formatObservations(observations, showResolved) {
-    const filtered = showResolved ? observations : observations.filter(o => !o.resolved);
+    const filtered = showResolved
+        ? observations
+        : observations.filter((o) => !o.resolved);
     if (filtered.length === 0) {
-        console.log(chalk.yellow(showResolved ? 'No observations found' : 'No unresolved observations'));
+        console.log(chalk.yellow(showResolved ? "No observations found" : "No unresolved observations"));
         return;
     }
+    // AC: @obs-list-display ac-1 - Include Resolved column when showing all observations
+    const headers = showResolved
+        ? [
+            chalk.bold("ID"),
+            chalk.bold("Type"),
+            chalk.bold("Resolved"),
+            chalk.bold("Workflow"),
+            chalk.bold("Created"),
+            chalk.bold("Content"),
+        ]
+        : [
+            chalk.bold("ID"),
+            chalk.bold("Type"),
+            chalk.bold("Workflow"),
+            chalk.bold("Created"),
+            chalk.bold("Content"),
+        ];
+    const colWidths = showResolved
+        ? [10, 10, 10, 20, 12, 40]
+        : [10, 10, 20, 12, 50];
     const table = new Table({
-        head: [
-            chalk.bold('ID'),
-            chalk.bold('Type'),
-            chalk.bold('Workflow'),
-            chalk.bold('Created'),
-            chalk.bold('Content'),
-        ],
+        head: headers,
         style: {
             head: [],
             border: [],
         },
-        colWidths: [10, 10, 20, 12, 50],
+        colWidths,
         wordWrap: true,
     });
     for (const obs of filtered) {
         const id = obs._ulid.substring(0, 8);
-        const workflow = obs.workflow_ref || '-';
-        const created = new Date(obs.created_at).toISOString().split('T')[0];
-        const content = obs.content.length > 47 ? obs.content.substring(0, 47) + '...' : obs.content;
-        table.push([id, obs.type, workflow, created, content]);
+        const workflow = obs.workflow_ref || "-";
+        const created = new Date(obs.created_at).toISOString().split("T")[0];
+        // Adjust content truncation based on available column width
+        const maxContentLen = showResolved ? 37 : 47;
+        const content = obs.content.length > maxContentLen
+            ? `${obs.content.substring(0, maxContentLen)}...`
+            : obs.content;
+        // AC: @obs-list-display ac-1 - Show ✓ for resolved, ✗ for unresolved
+        if (showResolved) {
+            const resolvedIndicator = obs.resolved
+                ? chalk.green("✓")
+                : chalk.red("✗");
+            table.push([id, obs.type, resolvedIndicator, workflow, created, content]);
+        }
+        else {
+            table.push([id, obs.type, workflow, created, content]);
+        }
     }
     console.log(table.toString());
 }
@@ -234,12 +285,12 @@ function formatObservations(observations, showResolved) {
  */
 export function registerMetaCommands(program) {
     const meta = program
-        .command('meta')
-        .description('Meta-spec commands (agents, workflows, conventions, observations)');
+        .command("meta")
+        .description("Meta-spec commands (agents, workflows, conventions, observations)");
     // AC-meta-manifest-1: kspec meta show outputs summary with counts
     meta
-        .command('show')
-        .description('Display meta-spec summary')
+        .command("show")
+        .description("Display meta-spec summary")
         .action(async () => {
         try {
             const ctx = await initContext();
@@ -261,8 +312,8 @@ export function registerMetaCommands(program) {
     });
     // AC-agent-1, AC-agent-2: kspec meta agents
     meta
-        .command('agents')
-        .description('List agents defined in meta-spec')
+        .command("agents")
+        .description("List agents defined in meta-spec")
         .action(async () => {
         try {
             const ctx = await initContext();
@@ -291,10 +342,12 @@ export function registerMetaCommands(program) {
         }
     });
     // AC-workflow-1, AC-workflow-2, AC-workflow-4: kspec meta workflows
+    // AC: @loop-mode-workflows ac-1 (--tag loop filtering)
     meta
-        .command('workflows')
-        .description('List workflows defined in meta-spec')
-        .option('--verbose', 'Show full workflow details with all steps')
+        .command("workflows")
+        .description("List workflows defined in meta-spec")
+        .option("--verbose", "Show full workflow details with all steps")
+        .option("--tag <tag>", "Filter workflows by tag (e.g., --tag loop)")
         .action(async (options) => {
         try {
             const ctx = await initContext();
@@ -303,13 +356,29 @@ export function registerMetaCommands(program) {
                 process.exit(EXIT_CODES.ERROR);
             }
             const metaCtx = await loadMetaContext(ctx);
-            const workflows = metaCtx.workflows || [];
+            let workflows = metaCtx.workflows || [];
+            // AC: @loop-mode-workflows ac-1 - Filter by tag
+            if (options.tag) {
+                workflows = workflows.filter((w) => {
+                    // Match by explicit tags array or by mode field (for "loop" tag)
+                    const tags = w.tags || [];
+                    if (tags.includes(options.tag))
+                        return true;
+                    // Special case: --tag loop also matches mode: loop
+                    if (options.tag === "loop" && w.mode === "loop")
+                        return true;
+                    return false;
+                });
+            }
             // AC-workflow-4: JSON output includes full workflow details
             output(workflows.map((workflow) => ({
                 id: workflow.id,
                 trigger: workflow.trigger,
                 description: workflow.description,
                 steps: workflow.steps,
+                mode: workflow.mode || "interactive",
+                based_on: workflow.based_on,
+                tags: workflow.tags || [],
             })), 
             // AC-workflow-1 (table) or AC-workflow-2 (verbose)
             () => {
@@ -328,9 +397,9 @@ export function registerMetaCommands(program) {
     });
     // AC-conv-1, AC-conv-2, AC-conv-5: kspec meta conventions
     meta
-        .command('conventions')
-        .description('List conventions defined in meta-spec')
-        .option('--domain <domain>', 'Filter by specific domain')
+        .command("conventions")
+        .description("List conventions defined in meta-spec")
+        .option("--domain <domain>", "Filter by specific domain")
         .action(async (options) => {
         try {
             const ctx = await initContext();
@@ -367,9 +436,10 @@ export function registerMetaCommands(program) {
         }
     });
     // meta-get-cmd: kspec meta get <ref>
+    // AC: @skill-meta-integration ac-1 - skills can be retrieved by id
     meta
-        .command('get <ref>')
-        .description('Get a meta item by reference (agent, workflow, convention, or observation)')
+        .command("get <ref>")
+        .description("Get a meta item by reference (agent, workflow, convention, observation, or skill)")
         .action(async (ref) => {
         try {
             const ctx = await initContext();
@@ -378,54 +448,17 @@ export function registerMetaCommands(program) {
                 process.exit(EXIT_CODES.ERROR);
             }
             const metaCtx = await loadMetaContext(ctx);
-            // Normalize reference
-            const normalizedRef = ref.startsWith('@') ? ref.substring(1) : ref;
-            // Search in all meta item types
-            const agents = metaCtx.agents || [];
-            const workflows = metaCtx.workflows || [];
-            const conventions = metaCtx.conventions || [];
-            const observations = metaCtx.observations || [];
-            // Try to find by ID or ULID prefix
-            let found = null;
-            let itemType = '';
-            // Check agents (by id or ULID)
-            const agent = agents.find((a) => a.id === normalizedRef || a._ulid.startsWith(normalizedRef));
-            if (agent) {
-                found = agent;
-                itemType = 'agent';
-            }
-            // Check workflows (by id or ULID)
-            if (!found) {
-                const workflow = workflows.find((w) => w.id === normalizedRef || w._ulid.startsWith(normalizedRef));
-                if (workflow) {
-                    found = workflow;
-                    itemType = 'workflow';
-                }
-            }
-            // Check conventions (by domain or ULID)
-            if (!found) {
-                const convention = conventions.find((c) => c.domain === normalizedRef || c._ulid.startsWith(normalizedRef));
-                if (convention) {
-                    found = convention;
-                    itemType = 'convention';
-                }
-            }
-            // Check observations (by ULID)
-            if (!found) {
-                const observation = observations.find((o) => o._ulid.startsWith(normalizedRef));
-                if (observation) {
-                    found = observation;
-                    itemType = 'observation';
-                }
-            }
-            if (!found) {
+            // AC: @skill-meta-integration ac-1 - Use unified resolver
+            const resolved = resolveMetaRef(metaCtx, ref);
+            if (!resolved) {
                 error(errors.reference.metaNotFound(ref));
                 process.exit(EXIT_CODES.ERROR);
             }
+            const { item: found, type: itemType } = resolved;
             // Output the item
             output(found, () => {
                 console.log(chalk.bold(`${itemType.charAt(0).toUpperCase() + itemType.slice(1)}: ${ref}`));
-                console.log(chalk.gray('─'.repeat(60)));
+                console.log(chalk.gray("─".repeat(60)));
                 console.log(JSON.stringify(found, null, 2));
             });
         }
@@ -435,10 +468,11 @@ export function registerMetaCommands(program) {
         }
     });
     // meta-list-cmd: kspec meta list
+    // AC: @skill-meta-integration ac-2 - skills can be filtered with --type skill
     meta
-        .command('list')
-        .description('List all meta items')
-        .option('--type <type>', 'Filter by type (agent, workflow, convention, observation)')
+        .command("list")
+        .description("List all meta items")
+        .option("--type <type>", "Filter by type (agent, workflow, convention, observation, skill)")
         .action(async (options) => {
         try {
             const ctx = await initContext();
@@ -449,58 +483,69 @@ export function registerMetaCommands(program) {
             const metaCtx = await loadMetaContext(ctx);
             const items = [];
             // Add agents
-            if (!options.type || options.type === 'agent') {
+            if (!options.type || options.type === "agent") {
                 for (const agent of metaCtx.agents || []) {
                     items.push({
                         id: agent.id,
-                        type: 'agent',
+                        type: "agent",
                         context: agent.name,
                         ulid: agent._ulid,
                     });
                 }
             }
             // Add workflows
-            if (!options.type || options.type === 'workflow') {
+            if (!options.type || options.type === "workflow") {
                 for (const workflow of metaCtx.workflows || []) {
                     items.push({
                         id: workflow.id,
-                        type: 'workflow',
+                        type: "workflow",
                         context: workflow.trigger,
                         ulid: workflow._ulid,
                     });
                 }
             }
             // Add conventions
-            if (!options.type || options.type === 'convention') {
+            if (!options.type || options.type === "convention") {
                 for (const convention of metaCtx.conventions || []) {
                     items.push({
                         id: convention.domain,
-                        type: 'convention',
+                        type: "convention",
                         context: `${convention.rules.length} rules`,
                         ulid: convention._ulid,
                     });
                 }
             }
             // Add observations
-            if (!options.type || options.type === 'observation') {
+            if (!options.type || options.type === "observation") {
                 for (const observation of metaCtx.observations || []) {
                     const ulidPrefix = observation._ulid.substring(0, 8);
                     items.push({
                         id: ulidPrefix,
-                        type: 'observation',
-                        context: `${observation.type} ${observation.resolved ? '(resolved)' : ''}`,
+                        type: "observation",
+                        context: `${observation.type} ${observation.resolved ? "(resolved)" : ""}`,
                         ulid: observation._ulid,
                     });
                 }
             }
+            // AC: @skill-meta-integration ac-2 - Add skills
+            if (!options.type || options.type === "skill") {
+                for (const skill of metaCtx.skills || []) {
+                    items.push({
+                        id: skill.id,
+                        type: "skill",
+                        context: skill.name || skill.description || skill.origin,
+                        ulid: skill._ulid,
+                    });
+                }
+            }
             // Output
             output(items, () => {
                 if (items.length === 0) {
-                    console.log(chalk.yellow('No meta items found'));
+                    console.log(chalk.yellow("No meta items found"));
                     return;
                 }
                 const table = new Table({
-                    head: [chalk.bold('ID'), chalk.bold('Type'), chalk.bold('Context')],
+                    head: [chalk.bold("ID"), chalk.bold("Type"), chalk.bold("Context")],
                     style: {
                         head: [],
                         border: [],
@@ -519,13 +564,12 @@ export function registerMetaCommands(program) {
     });
     // AC-obs-1: kspec meta observe <type> <content>
     // AC: @meta-observe-cmd from-inbox-conversion
-    meta
-        .command('observe [type] [content]')
-        .description('Create an observation (friction, success, question, idea)')
-        .option('--workflow <ref>', 'Reference to workflow this observation relates to')
-        .option('--author <author>', 'Author of the observation')
-        .option('--from-inbox <ref>', 'Convert inbox item to observation')
-        .option('--type <type>', 'Override type when using --from-inbox (defaults to idea)')
+    markMutating(meta.command("observe [type] [content]"))
+        .description("Create an observation (friction, success, question, idea)")
+        .option("--workflow <ref>", "Reference to workflow this observation relates to")
+        .option("--author <author>", "Author of the observation")
+        .option("--from-inbox <ref>", "Convert inbox item to observation")
+        .option("--type <type>", "Override type when using --from-inbox (defaults to idea)")
         .action(async (type, content, options) => {
         try {
             const ctx = await initContext();
@@ -546,51 +590,65 @@ export function registerMetaCommands(program) {
                 // Use inbox item content
                 const observationContent = item.text;
                 // Type defaults to 'idea' but can be overridden with --type flag
-                const observationType = (options.type || 'idea');
+                const observationType = (options.type || "idea");
                 // Validate observation type
-                const validTypes = ['friction', 'success', 'question', 'idea'];
+                const validTypes = [
+                    "friction",
+                    "success",
+                    "question",
+                    "idea",
+                ];
                 if (!validTypes.includes(observationType)) {
                     error(errors.validation.invalidObservationType(observationType));
-                    console.log(`Valid types: ${validTypes.join(', ')}`);
+                    console.log(`Valid types: ${validTypes.join(", ")}`);
                     process.exit(EXIT_CODES.ERROR);
                 }
                 // Create observation
                 const observation = createObservation(observationType, observationContent, {
                     workflow_ref: options.workflow,
                     author: options.author,
+                    configAuthor: ctx.config?.identity?.author,
                 });
                 // Save observation
                 await saveObservation(ctx, observation);
                 // Delete inbox item
                 const deleted = await deleteInboxItem(ctx, item._ulid);
                 if (!deleted) {
-                    error('Failed to delete inbox item after creating observation');
+                    error("Failed to delete inbox item after creating observation");
                     process.exit(EXIT_CODES.ERROR);
                 }
-                await commitIfShadow(ctx.shadow, 'meta-observe-from-inbox', observation._ulid.substring(0, 8), `Convert inbox item to ${observationType} observation`);
+                await commitIfShadow(ctx.shadow, "meta-observe-from-inbox", observation._ulid.substring(0, 8), `Convert inbox item to ${observationType} observation`);
                 // Return observation ref
                 output(observation, () => success(`Created observation: ${observation._ulid.substring(0, 8)}`));
                 return;
             }
             // Standard observe flow (without --from-inbox)
             if (!type || !content) {
-                error('Type and content are required when not using --from-inbox');
+                error("Type and content are required when not using --from-inbox");
                 process.exit(EXIT_CODES.ERROR);
             }
             // Validate observation type
-            const validTypes = ['friction', 'success', 'question', 'idea'];
+            const validTypes = [
+                "friction",
+                "success",
+                "question",
+                "idea",
+            ];
             if (!validTypes.includes(type)) {
                 error(errors.validation.invalidObservationType(type));
-                console.log(`Valid types: ${validTypes.join(', ')}`);
+                console.log(`Valid types: ${validTypes.join(", ")}`);
                 process.exit(EXIT_CODES.ERROR);
             }
             // Create observation
             const observation = createObservation(type, content, {
                 workflow_ref: options.workflow,
                 author: options.author,
+                configAuthor: ctx.config?.identity?.author,
             });
             // Save to manifest
             await saveObservation(ctx, observation);
+            // AC: @trait-shadow-commit ac-1
+            await commitIfShadow(ctx.shadow, "meta-observe", observation._ulid.substring(0, 8), type);
             // AC-obs-1: outputs "OK Created observation: <ULID-prefix>"
             // In JSON mode, return the created observation object
             output(observation, () => success(`Created observation: ${observation._ulid.substring(0, 8)}`));
@@ -601,14 +659,16 @@ export function registerMetaCommands(program) {
         }
     });
     // AC-obs-2, AC-obs-5: kspec meta observations
+    // AC: @observation-content-search ac-search-flag, ac-regex-support, ac-combined-filters
     meta
-        .command('observations')
-        .description('List observations (shows unresolved by default)')
-        .option('--type <type>', 'Filter by observation type (friction/success/question/idea)')
-        .option('--workflow <ref>', 'Filter by workflow reference')
-        .option('--all', 'Include resolved observations')
-        .option('--promoted', 'Show only observations promoted to tasks')
-        .option('--pending-resolution', 'Show observations with completed tasks awaiting resolution')
+        .command("observations")
+        .description("List observations (shows unresolved by default)")
+        .option("--type <type>", "Filter by observation type (friction/success/question/idea)")
+        .option("--workflow <ref>", "Filter by workflow reference")
+        .option("--all", "Include resolved observations")
+        .option("--promoted", "Show only observations promoted to tasks")
+        .option("--pending-resolution", "Show observations with completed tasks awaiting resolution")
+        .option("--search <pattern>", "Search observations by regex pattern (matches content)")
         .action(async (options) => {
         try {
             const ctx = await initContext();
@@ -641,7 +701,18 @@ export function registerMetaCommands(program) {
                         return false;
                     const item = taskResult.item;
                     // Type guard: check if item is a task (has status and depends_on properties)
-                    return 'status' in item && 'depends_on' in item && item.status === 'completed';
+                    return ("status" in item &&
+                        "depends_on" in item &&
+                        item.status === "completed");
+                });
+            }
+            // AC: @observation-content-search ac-search-flag, ac-regex-support, ac-combined-filters, ac-search-all-fields
+            // Apply --search filter using regex pattern (consistent with kspec search behavior)
+            if (options.search) {
+                const { grepItem } = await import("../../utils/grep.js");
+                observations = observations.filter((obs) => {
+                    const match = grepItem(obs, options.search);
+                    return match !== null;
                 });
             }
             // AC-obs-5: JSON output includes full observation objects
@@ -667,12 +738,11 @@ export function registerMetaCommands(program) {
         }
     });
     // AC-obs-3, AC-obs-6, AC-obs-8: kspec meta promote
-    meta
-        .command('promote <ref>')
-        .description('Promote observation to a task')
-        .requiredOption('--title <title>', 'Task title')
-        .option('--priority <priority>', 'Task priority (1-5)', '2')
-        .option('--force', 'Force promotion even if observation is resolved')
+    markMutating(meta.command("promote <ref>"))
+        .description("Promote observation to a task")
+        .requiredOption("--title <title>", "Task title")
+        .option("--priority <priority>", "Task priority (1-5)", "2")
+        .option("--force", "Force promotion even if observation is resolved")
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
@@ -681,14 +751,17 @@ export function registerMetaCommands(program) {
                 process.exit(EXIT_CODES.ERROR);
             }
             const metaCtx = await loadMetaContext(ctx);
-            const observations = metaCtx.observations || [];
-            // Find observation
-            const normalizedRef = ref.startsWith('@') ? ref.substring(1) : ref;
-            const observation = observations.find((o) => o._ulid.startsWith(normalizedRef));
-            if (!observation) {
+            // Use unified resolver - promotes only observations
+            const resolved = resolveMetaRef(metaCtx, ref);
+            if (!resolved) {
                 error(errors.reference.observationNotFound(ref));
                 process.exit(EXIT_CODES.ERROR);
             }
+            if (resolved.type !== "observation") {
+                error(`Cannot promote ${resolved.type}. Only observations can be promoted to tasks.`);
+                process.exit(EXIT_CODES.ERROR);
+            }
+            const observation = resolved.item;
             // AC-obs-6: Check if already promoted
             if (observation.promoted_to) {
                 error(errors.conflict.observationAlreadyPromoted(observation.promoted_to));
@@ -699,21 +772,33 @@ export function registerMetaCommands(program) {
                 error(errors.operation.cannotPromoteResolved);
                 process.exit(EXIT_CODES.ERROR);
             }
+            // Validate priority
+            const priorityResult = parseIntOption(options.priority, {
+                min: 1,
+                max: 5,
+                name: "Priority",
+            });
+            if (!priorityResult.ok) {
+                error(priorityResult.error);
+                process.exit(EXIT_CODES.VALIDATION_FAILED);
+            }
             // AC-obs-3: Create task with title, description from observation, meta_ref, and origin
             const task = createTask({
                 title: options.title,
                 description: observation.content,
-                priority: Number.parseInt(options.priority, 10),
+                priority: priorityResult.value,
                 meta_ref: observation.workflow_ref,
-                origin: 'observation_promotion',
+                origin: "observation_promotion",
             });
             // Save task
             await saveTask(ctx, task);
-            await commitIfShadow(ctx.shadow, 'task-add', task.slugs[0] || task._ulid.slice(0, 8), task.title);
+            await commitIfShadow(ctx.shadow, "task-add", task.slugs[0] || task._ulid.slice(0, 8), task.title);
             const taskRef = `@${task._ulid.substring(0, 8)}`;
             // Update observation with promoted_to field
             observation.promoted_to = taskRef;
             await saveObservation(ctx, observation);
+            // AC: @trait-shadow-commit ac-1
+            await commitIfShadow(ctx.shadow, "observation-promote", observation._ulid.substring(0, 8));
             // AC-obs-3: outputs "OK Created task: <ULID-prefix>"
             // In JSON mode, return the created task object
             output(task, () => success(`Created task: ${taskRef.substring(0, 9)}`));
@@ -724,10 +809,16 @@ export function registerMetaCommands(program) {
         }
     });
     // AC-obs-4, AC-obs-7, AC-obs-9: kspec meta resolve
-    meta
-        .command('resolve <ref> [resolution]')
-        .description('Resolve an observation')
-        .action(async (ref, resolution) => {
+    // AC: @trait-multi-ref-batch - Batch support with --refs flag
+    markMutating(meta.command("resolve [ref] [resolution]"))
+        .description("Resolve an observation (or multiple with --refs)")
+        .option("--refs <refs...>", "Resolve multiple observations by ref")
+        .option("--resolution <text>", "Resolution text (required for batch mode unless observations have promoted tasks)")
+        .addHelpText("after", `
+Examples:
+  $ kspec meta resolve @obs-ref "Fixed in PR #123"
+  $ kspec meta resolve --refs @obs1 @obs2 --resolution "Resolved in batch"`)
+        .action(async (ref, resolutionArg, options) => {
         try {
             const ctx = await initContext();
             if (!ctx.manifestPath) {
@@ -736,69 +827,100 @@ export function registerMetaCommands(program) {
             }
             const metaCtx = await loadMetaContext(ctx);
             const observations = metaCtx.observations || [];
-            // Find observation
-            const normalizedRef = ref.startsWith('@') ? ref.substring(1) : ref;
-            const observation = observations.find((o) => o._ulid.startsWith(normalizedRef));
-            if (!observation) {
-                error(errors.reference.observationNotFound(ref));
-                process.exit(EXIT_CODES.ERROR);
-            }
-            // AC-obs-7: Check if already resolved
-            if (observation.resolved) {
-                const resolvedDate = new Date(observation.resolved_at).toISOString().split('T')[0];
-                const resolutionText = observation.resolution || '';
-                const truncated = resolutionText.length > 50
-                    ? resolutionText.substring(0, 50) + '...'
-                    : resolutionText;
-                error(errors.conflict.observationAlreadyResolved(resolvedDate, truncated));
-                process.exit(EXIT_CODES.CONFLICT);
-            }
-            // AC-obs-9: Auto-populate resolution from task completion if promoted
-            let finalResolution = resolution;
-            if (!finalResolution && observation.promoted_to) {
-                // Fetch task to get completion reason
-                const tasks = await loadAllTasks(ctx);
-                const items = await loadAllItems(ctx);
-                const index = new ReferenceIndex(tasks, items);
-                const taskResult = index.resolve(observation.promoted_to);
-                if (taskResult.ok) {
-                    const item = taskResult.item;
-                    // Type guard: ensure this is a task (has status and depends_on properties)
-                    if ('status' in item && 'depends_on' in item) {
-                        const task = item;
-                        if (task.status === 'completed' && task.closed_reason) {
-                            finalResolution = `Resolved via task ${observation.promoted_to}: ${task.closed_reason}`;
-                        }
-                        else if (task.status === 'completed') {
-                            finalResolution = `Resolved via task ${observation.promoted_to}`;
+            // Load tasks/items for auto-resolution from promoted tasks
+            const tasks = await loadAllTasks(ctx);
+            const items = await loadAllItems(ctx);
+            const index = new ReferenceIndex(tasks, items);
+            // Resolution can come from positional arg or --resolution flag
+            const resolution = resolutionArg || options.resolution;
+            // AC: @trait-multi-ref-batch ac-8 - Deduplicate refs
+            const refsFlag = options.refs
+                ? [...new Set(options.refs)]
+                : undefined;
+            // AC: @trait-multi-ref-batch ac-1, ac-2, ac-3, ac-4, ac-5
+            const result = await executeBatchOperation({
+                positionalRef: ref,
+                refsFlag,
+                context: { ctx, observations, tasks, items, index, resolution },
+                items: observations,
+                index: index,
+                resolveRef: (refStr, obsList) => {
+                    return resolveObservationRefForBatch(refStr, obsList);
+                },
+                executeOperation: async (observation, { ctx, tasks, items, index, resolution }) => {
+                    // AC-obs-7: Check if already resolved
+                    if (observation.resolved) {
+                        const resolvedDate = new Date(observation.resolved_at)
+                            .toISOString()
+                            .split("T")[0];
+                        const resolutionText = observation.resolution || "";
+                        const truncated = resolutionText.length > 50
+                            ? `${resolutionText.substring(0, 50)}...`
+                            : resolutionText;
+                        return {
+                            success: false,
+                            error: `Already resolved on ${resolvedDate}: ${truncated}`,
+                        };
+                    }
+                    // AC-obs-9: Auto-populate resolution from task completion if promoted
+                    let finalResolution = resolution;
+                    if (!finalResolution && observation.promoted_to) {
+                        const taskResult = index.resolve(observation.promoted_to);
+                        if (taskResult.ok) {
+                            const item = taskResult.item;
+                            // Type guard: ensure this is a task
+                            if ("status" in item && "depends_on" in item) {
+                                const task = item;
+                                if (task.status === "completed" && task.closed_reason) {
+                                    finalResolution = `Resolved via task ${observation.promoted_to}: ${task.closed_reason}`;
+                                }
+                                else if (task.status === "completed") {
+                                    finalResolution = `Resolved via task ${observation.promoted_to}`;
+                                }
+                                else {
+                                    return {
+                                        success: false,
+                                        error: `Task ${observation.promoted_to} is not completed yet`,
+                                    };
+                                }
+                            }
+                            else {
+                                return {
+                                    success: false,
+                                    error: `Reference ${observation.promoted_to} is not a task`,
+                                };
+                            }
                         }
                         else {
-                            error(`Task ${observation.promoted_to} is not completed yet`);
-                            process.exit(EXIT_CODES.ERROR);
+                            return {
+                                success: false,
+                                error: `Task ${observation.promoted_to} not found`,
+                            };
                         }
                     }
-                    else {
-                        error(`Reference ${observation.promoted_to} is not a task`);
-                        process.exit(EXIT_CODES.ERROR);
+                    if (!finalResolution) {
+                        return {
+                            success: false,
+                            error: "Resolution text required",
+                        };
                     }
-                }
-                else {
-                    error(`Task ${observation.promoted_to} not found`);
-                    process.exit(EXIT_CODES.ERROR);
-                }
-            }
-            if (!finalResolution) {
-                error(errors.validation.resolutionRequired);
-                process.exit(EXIT_CODES.ERROR);
-            }
-            // AC-obs-4: Update observation
-            observation.resolved = true;
-            observation.resolution = finalResolution;
-            observation.resolved_at = new Date().toISOString();
-            observation.resolved_by = observation.author; // Use same author
-            await saveObservation(ctx, observation);
-            // AC-obs-4: outputs "OK Resolved: <ULID-prefix>"
-            success(`Resolved: ${observation._ulid.substring(0, 8)}`);
+                    // AC-obs-4: Update observation
+                    observation.resolved = true;
+                    observation.resolution = finalResolution;
+                    observation.resolved_at = new Date().toISOString();
+                    observation.resolved_by = observation.author;
+                    await saveObservation(ctx, observation);
+                    // AC: @trait-shadow-commit ac-1
+                    await commitIfShadow(ctx.shadow, "observation-resolve", observation._ulid.substring(0, 8));
+                    return {
+                        success: true,
+                        message: `Resolved: ${observation._ulid.substring(0, 8)}`,
+                    };
+                },
+                getUlid: (obs) => obs._ulid,
+            });
+            // AC: @trait-multi-ref-batch ac-5, ac-7 - Output formatting
+            formatBatchOutput(result, "Resolve");
         }
         catch (err) {
             error(errors.failures.resolveObservation, err);
@@ -806,23 +928,31 @@ export function registerMetaCommands(program) {
         }
     });
     // Meta add command - create new meta items
-    meta
-        .command('add <type>')
-        .description('Create a new meta item (agent, workflow, or convention)')
-        .option('--id <id>', 'Semantic ID (required for agents and workflows)')
-        .option('--domain <domain>', 'Domain (required for conventions)')
-        .option('--name <name>', 'Name (for agents)')
-        .option('--trigger <trigger>', 'Trigger (for workflows)')
-        .option('--description <desc>', 'Description')
-        .option('--capability <cap...>', 'Capabilities (for agents)')
-        .option('--tool <tool...>', 'Tools (for agents)')
-        .option('--convention <conv...>', 'Convention references (for agents)')
-        .option('--rule <rule...>', 'Rules (for conventions)')
+    markMutating(meta.command("add <type>"))
+        .description("Create a new meta item (agent, workflow, or convention)")
+        .option("--id <id>", "Semantic ID (required for agents and workflows)")
+        .option("--domain <domain>", "Domain (required for conventions)")
+        .option("--name <name>", "Name (for agents)")
+        .option("--trigger <trigger>", "Trigger (for workflows)")
+        .option("--description <desc>", "Description")
+        .option("--capability <cap...>", "Capabilities (for agents)")
+        .option("--tool <tool...>", "Tools (for agents)")
+        .option("--convention <conv...>", "Convention references (for agents)")
+        .option("--rule <rule...>", "Rules (for conventions)")
+        .option("--steps <json>", "Workflow steps as JSON array (for workflows)")
+        .option("--mode <mode>", "Workflow mode: interactive (default) or loop (for workflows)")
+        .option("--based-on <ref>", "Base workflow reference (for loop workflows)")
+        .option("--tag <tag...>", "Tags for the workflow (for workflows)")
+        .addHelpText("after", `
+Examples:
+  $ kspec meta add agent --id my-agent --name "My Agent" --capability search code
+  $ kspec meta add convention --domain testing --rule "Always test" --rule "Use mocks"
+  $ kspec meta add workflow --id my-flow --trigger manual --tag automation ci`)
         .action(async (type, options) => {
         try {
             const ctx = await initContext();
             // Validate type
-            const validTypes = ['agent', 'workflow', 'convention'];
+            const validTypes = ["agent", "workflow", "convention"];
             if (!validTypes.includes(type)) {
                 error(errors.validation.invalidType(type, validTypes));
                 process.exit(EXIT_CODES.ERROR);
@@ -831,7 +961,7 @@ export function registerMetaCommands(program) {
             const itemUlid = ulid();
             // Create the item based on type
             let item;
-            if (type === 'agent') {
+            if (type === "agent") {
                 // Validate required fields
                 if (!options.id) {
                     error(errors.validation.agentRequiresId);
@@ -845,13 +975,13 @@ export function registerMetaCommands(program) {
                     _ulid: itemUlid,
                     id: options.id,
                     name: options.name,
-                    description: options.description || '',
+                    description: options.description || "",
                     capabilities: options.capability || [],
                     tools: options.tool || [],
                     conventions: options.convention || [],
                 };
             }
-            else if (type === 'workflow') {
+            else if (type === "workflow") {
                 // Validate required fields
                 if (!options.id) {
                     error(errors.validation.workflowRequiresId);
@@ -861,12 +991,50 @@ export function registerMetaCommands(program) {
                     error(errors.validation.workflowRequiresTrigger);
                     process.exit(EXIT_CODES.ERROR);
                 }
+                // Parse and validate --steps if provided
+                let steps = [];
+                if (options.steps) {
+                    // AC: @meta-add-cmd ac-2 - Parse JSON
+                    let parsedSteps;
+                    try {
+                        parsedSteps = JSON.parse(options.steps);
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        error(errors.validation.invalidStepsJson(message));
+                        process.exit(EXIT_CODES.ERROR);
+                    }
+                    // AC: @meta-add-cmd ac-3 - Verify it's an array
+                    if (!Array.isArray(parsedSteps)) {
+                        error(errors.validation.stepsNotArray);
+                        process.exit(EXIT_CODES.ERROR);
+                    }
+                    // AC: @meta-add-cmd ac-4 - Validate with schema
+                    const result = z.array(WorkflowStepSchema).safeParse(parsedSteps);
+                    if (!result.success) {
+                        const issues = result.error.issues
+                            .map((i) => `${i.path.join(".")}: ${i.message}`)
+                            .join("; ");
+                        error(errors.validation.invalidStepsSchema(issues));
+                        process.exit(EXIT_CODES.ERROR);
+                    }
+                    steps = result.data;
+                }
+                // Validate mode if provided
+                const validModes = ["interactive", "loop"];
+                if (options.mode && !validModes.includes(options.mode)) {
+                    error(`Invalid mode: ${options.mode}. Valid modes: ${validModes.join(", ")}`);
+                    process.exit(EXIT_CODES.ERROR);
+                }
                 item = {
                     _ulid: itemUlid,
                     id: options.id,
                     trigger: options.trigger,
-                    description: options.description || '',
-                    steps: [],
+                    description: options.description || "",
+                    steps,
+                    ...(options.mode && { mode: options.mode }),
+                    ...(options.basedOn && { based_on: options.basedOn }),
+                    ...(options.tag && options.tag.length > 0 && { tags: parseTagsArray(options.tag) }),
                 };
             }
             else {
@@ -884,12 +1052,14 @@ export function registerMetaCommands(program) {
             }
             // Save the item
             await saveMetaItem(ctx, item, type);
+            // AC: @trait-shadow-commit ac-1
+            await commitIfShadow(ctx.shadow, `meta-add-${type}`, itemUlid.substring(0, 8), "id" in item ? item.id : "domain" in item ? item.domain : undefined);
             if (isJsonMode()) {
                 // In JSON mode, output the item data directly
                 console.log(JSON.stringify(item, null, 2));
             }
             else {
-                const idOrDomain = 'id' in item ? item.id : 'domain' in item ? item.domain : itemUlid;
+                const idOrDomain = "id" in item ? item.id : "domain" in item ? item.domain : itemUlid;
                 success(`Created ${type}: ${idOrDomain} (@${itemUlid.substring(0, 8)})`);
             }
         }
@@ -899,55 +1069,35 @@ export function registerMetaCommands(program) {
         }
     });
     // Meta set command - update existing meta items
-    meta
-        .command('set <ref>')
-        .description('Update an existing meta item')
-        .option('--name <name>', 'Update name (for agents)')
-        .option('--description <desc>', 'Update description')
-        .option('--trigger <trigger>', 'Update trigger (for workflows)')
-        .option('--add-capability <cap>', 'Add capability (for agents)')
-        .option('--add-tool <tool>', 'Add tool (for agents)')
-        .option('--add-convention <conv>', 'Add convention reference (for agents)')
-        .option('--add-rule <rule>', 'Add rule (for conventions)')
+    markMutating(meta.command("set <ref>"))
+        .description("Update an existing meta item")
+        .option("--name <name>", "Update name (for agents)")
+        .option("--description <desc>", "Update description")
+        .option("--trigger <trigger>", "Update trigger (for workflows)")
+        .option("--add-capability <cap>", "Add capability (for agents)")
+        .option("--add-tool <tool>", "Add tool (for agents)")
+        .option("--add-convention <conv>", "Add convention reference (for agents)")
+        .option("--add-rule <rule>", "Add rule (for conventions)")
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
             const metaCtx = await loadMetaContext(ctx);
-            // Find the item using unified lookup
-            const normalizedRef = ref.startsWith('@') ? ref.substring(1) : ref;
-            let found = null;
-            let itemType = null;
-            // Search in agents
-            const agents = metaCtx.manifest?.agents || [];
-            const agent = agents.find((a) => a.id === normalizedRef || a._ulid.startsWith(normalizedRef));
-            if (agent) {
-                found = agent;
-                itemType = 'agent';
-            }
-            // Search in workflows
-            if (!found) {
-                const workflows = metaCtx.manifest?.workflows || [];
-                const workflow = workflows.find((w) => w.id === normalizedRef || w._ulid.startsWith(normalizedRef));
-                if (workflow) {
-                    found = workflow;
-                    itemType = 'workflow';
-                }
-            }
-            // Search in conventions
-            if (!found) {
-                const conventions = metaCtx.manifest?.conventions || [];
-                const convention = conventions.find((c) => c.domain === normalizedRef || c._ulid.startsWith(normalizedRef));
-                if (convention) {
-                    found = convention;
-                    itemType = 'convention';
-                }
-            }
-            if (!found || !itemType) {
+            // Use unified resolver
+            const resolved = resolveMetaRef(metaCtx, ref);
+            if (!resolved) {
                 error(errors.reference.metaNotFound(ref));
                 process.exit(EXIT_CODES.ERROR);
             }
+            // meta set only supports agent, workflow, convention
+            // Skills have their own `kspec skill set` command
+            const { item, type: itemType } = resolved;
+            if (itemType !== "agent" && itemType !== "workflow" && itemType !== "convention") {
+                error(`Cannot use 'meta set' with ${itemType}. Use 'kspec ${itemType === "skill" ? "skill" : "meta"} ${itemType === "observation" ? "resolve" : "set"} ${ref}' instead.`);
+                process.exit(EXIT_CODES.ERROR);
+            }
+            const found = item;
             // Update fields based on type
-            if (itemType === 'agent') {
+            if (itemType === "agent") {
                 const item = found;
                 if (options.name)
                     item.name = options.name;
@@ -969,7 +1119,7 @@ export function registerMetaCommands(program) {
                     }
                 }
             }
-            else if (itemType === 'workflow') {
+            else if (itemType === "workflow") {
                 const item = found;
                 if (options.trigger)
                     item.trigger = options.trigger;
@@ -987,14 +1137,16 @@ export function registerMetaCommands(program) {
             }
             // Save the updated item
             await saveMetaItem(ctx, found, itemType);
+            // AC: @trait-shadow-commit ac-1
+            await commitIfShadow(ctx.shadow, `meta-set-${itemType}`, found._ulid.substring(0, 8));
             if (isJsonMode()) {
                 // In JSON mode, output the item data directly
                 console.log(JSON.stringify(found, null, 2));
             }
             else {
-                const idOrDomain = itemType === 'agent'
+                const idOrDomain = itemType === "agent"
                     ? found.id
-                    : itemType === 'workflow'
+                    : itemType === "workflow"
                         ? found.id
                         : found.domain;
                 success(`Updated ${itemType}: ${idOrDomain}`);
@@ -1006,60 +1158,40 @@ export function registerMetaCommands(program) {
         }
     });
     // Meta delete command - delete meta items
-    meta
-        .command('delete <ref>')
-        .description('Delete a meta item')
-        .option('--confirm', 'Skip confirmation prompt')
+    markMutating(meta.command("delete <ref>"))
+        .description("Delete a meta item")
+        .option("--confirm", "Skip confirmation prompt")
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
             const metaCtx = await loadMetaContext(ctx);
-            // Find the item to determine type
-            const normalizedRef = ref.startsWith('@') ? ref.substring(1) : ref;
-            let itemType = null;
-            let itemUlid = null;
-            let itemLabel = null;
-            // Search in agents
-            const agents = metaCtx.manifest?.agents || [];
-            const agent = agents.find((a) => a.id === normalizedRef || a._ulid.startsWith(normalizedRef));
-            if (agent) {
-                itemType = 'agent';
-                itemUlid = agent._ulid;
-                itemLabel = `agent ${agent.id}`;
-            }
-            // Search in workflows
-            if (!itemType) {
-                const workflows = metaCtx.manifest?.workflows || [];
-                const workflow = workflows.find((w) => w.id === normalizedRef || w._ulid.startsWith(normalizedRef));
-                if (workflow) {
-                    itemType = 'workflow';
-                    itemUlid = workflow._ulid;
-                    itemLabel = `workflow ${workflow.id}`;
-                }
+            // Use unified resolver
+            const resolved = resolveMetaRef(metaCtx, ref);
+            if (!resolved) {
+                error(errors.reference.metaNotFound(ref));
+                process.exit(EXIT_CODES.ERROR);
             }
-            // Search in conventions
-            if (!itemType) {
-                const conventions = metaCtx.manifest?.conventions || [];
-                const convention = conventions.find((c) => c.domain === normalizedRef || c._ulid.startsWith(normalizedRef));
-                if (convention) {
-                    itemType = 'convention';
-                    itemUlid = convention._ulid;
-                    itemLabel = `convention ${convention.domain}`;
-                }
+            // meta delete does not support skills - they use `kspec skill delete`
+            if (resolved.type === "skill") {
+                error(`Cannot use 'meta delete' with skills. Use 'kspec skill delete ${ref}' instead.`);
+                process.exit(EXIT_CODES.ERROR);
             }
-            // Search in observations
-            if (!itemType) {
-                const observations = metaCtx.observations || [];
-                const observation = observations.find((o) => o._ulid.startsWith(normalizedRef));
-                if (observation) {
-                    itemType = 'observation';
-                    itemUlid = observation._ulid;
-                    itemLabel = `observation ${observation._ulid.substring(0, 8)}`;
-                }
+            const itemType = resolved.type;
+            const itemUlid = resolved.ulid;
+            // Build human-readable label for the item
+            let itemLabel;
+            const item = resolved.item;
+            if (itemType === "agent" && "id" in item) {
+                itemLabel = `agent ${item.id}`;
             }
-            if (!itemType || !itemUlid || !itemLabel) {
-                error(errors.reference.metaNotFound(ref));
-                process.exit(EXIT_CODES.ERROR);
+            else if (itemType === "workflow" && "id" in item) {
+                itemLabel = `workflow ${item.id}`;
+            }
+            else if (itemType === "convention" && "domain" in item) {
+                itemLabel = `convention ${item.domain}`;
+            }
+            else {
+                itemLabel = `observation ${itemUlid.substring(0, 8)}`;
             }
             // Check for dangling references (unless --confirm is used to override)
             if (!options.confirm) {
@@ -1076,12 +1208,12 @@ export function registerMetaCommands(program) {
                 if (referencingTasks.length > 0) {
                     const taskRefs = referencingTasks
                         .map((t) => `@${t.slugs?.[0] || t._ulid.substring(0, 8)}`)
-                        .join(', ');
+                        .join(", ");
                     error(errors.operation.cannotDeleteReferencedByTasks(itemLabel, referencingTasks.length, taskRefs));
                     process.exit(EXIT_CODES.ERROR);
                 }
                 // Check observations with workflow_ref (only for workflows)
-                if (itemType === 'workflow') {
+                if (itemType === "workflow") {
                     const observations = metaCtx.observations || [];
                     const referencingObservations = observations.filter((o) => {
                         if (!o.workflow_ref)
@@ -1094,7 +1226,7 @@ export function registerMetaCommands(program) {
                     if (referencingObservations.length > 0) {
                         const obsRefs = referencingObservations
                             .map((o) => `@${o._ulid.substring(0, 8)}`)
-                            .join(', ');
+                            .join(", ");
                         error(errors.operation.cannotDeleteReferencedByObservations(itemLabel, referencingObservations.length, obsRefs));
                         process.exit(EXIT_CODES.ERROR);
                     }
@@ -1109,6 +1241,8 @@ export function registerMetaCommands(program) {
                 error(errors.operation.deleteItemFailed(itemLabel));
                 process.exit(EXIT_CODES.ERROR);
             }
+            // AC: @trait-shadow-commit ac-1
+            await commitIfShadow(ctx.shadow, `meta-delete-${itemType}`, itemUlid.substring(0, 8));
             success(`Deleted ${itemLabel}`);
         }
         catch (err) {
@@ -1117,10 +1251,9 @@ export function registerMetaCommands(program) {
         }
     });
     // meta-focus-cmd: kspec meta focus [ref]
-    meta
-        .command('focus [ref]')
-        .description('Get or set session focus')
-        .option('--clear', 'Clear current focus')
+    markMutating(meta.command("focus [ref]"))
+        .description("Get or set session focus")
+        .option("--clear", "Clear current focus")
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
@@ -1133,7 +1266,7 @@ export function registerMetaCommands(program) {
             if (options.clear) {
                 sessionCtx.focus = null;
                 await saveSessionContext(ctx, sessionCtx);
-                output({ focus: null }, () => success('Cleared session focus'));
+                output({ focus: null }, () => success("Cleared session focus"));
                 return;
             }
             // Show current focus
@@ -1143,13 +1276,13 @@ export function registerMetaCommands(program) {
                         console.log(`Current focus: ${sessionCtx.focus}`);
                     }
                     else {
-                        console.log(chalk.yellow('No focus set'));
+                        console.log(chalk.yellow("No focus set"));
                     }
                 });
                 return;
             }
             // Set focus to ref
-            sessionCtx.focus = ref.startsWith('@') ? ref : `@${ref}`;
+            sessionCtx.focus = normalizeRefInput(ref);
             await saveSessionContext(ctx, sessionCtx);
             output({ focus: sessionCtx.focus }, () => success(`Set focus to: ${sessionCtx.focus}`));
         }
@@ -1159,9 +1292,8 @@ export function registerMetaCommands(program) {
         }
     });
     // meta-thread-cmd: kspec meta thread <action> [text]
-    meta
-        .command('thread <action> [text]')
-        .description('Manage active threads')
+    markMutating(meta.command("thread <action> [text]"))
+        .description("Manage active threads")
         .action(async (action, text) => {
         try {
             const ctx = await initContext();
@@ -1171,13 +1303,13 @@ export function registerMetaCommands(program) {
             }
             const sessionCtx = await loadSessionContext(ctx);
             // List threads
-            if (action === 'list') {
+            if (action === "list") {
                 output({ threads: sessionCtx.threads }, () => {
                     if (sessionCtx.threads.length === 0) {
-                        console.log(chalk.yellow('No active threads'));
+                        console.log(chalk.yellow("No active threads"));
                     }
                     else {
-                        console.log('Active threads:');
+                        console.log("Active threads:");
                         sessionCtx.threads.forEach((thread, idx) => {
                             console.log(`  ${idx + 1}. ${thread}`);
                         });
@@ -1186,16 +1318,16 @@ export function registerMetaCommands(program) {
                 return;
             }
             // Clear all threads
-            if (action === 'clear') {
+            if (action === "clear") {
                 sessionCtx.threads = [];
                 await saveSessionContext(ctx, sessionCtx);
-                output({ threads: [] }, () => success('Cleared all threads'));
+                output({ threads: [] }, () => success("Cleared all threads"));
                 return;
             }
             // Add thread
-            if (action === 'add') {
+            if (action === "add") {
                 if (!text) {
-                    error('Thread text is required for add action');
+                    error("Thread text is required for add action");
                     process.exit(EXIT_CODES.ERROR);
                 }
                 sessionCtx.threads.push(text);
@@ -1204,13 +1336,15 @@ export function registerMetaCommands(program) {
                 return;
             }
             // Remove thread by index (1-based)
-            if (action === 'remove') {
+            if (action === "remove") {
                 if (!text) {
-                    error('Index is required for remove action');
+                    error("Index is required for remove action");
                     process.exit(EXIT_CODES.ERROR);
                 }
                 const index = parseInt(text, 10);
-                if (isNaN(index) || index < 1 || index > sessionCtx.threads.length) {
+                if (Number.isNaN(index) ||
+                    index < 1 ||
+                    index > sessionCtx.threads.length) {
                     error(`Invalid index: ${text}. Must be between 1 and ${sessionCtx.threads.length}`);
                     process.exit(EXIT_CODES.ERROR);
                 }
@@ -1229,9 +1363,8 @@ export function registerMetaCommands(program) {
         }
     });
     // meta-question-cmd: kspec meta question <action> [text]
-    meta
-        .command('question <action> [text]')
-        .description('Manage open questions')
+    markMutating(meta.command("question <action> [text]"))
+        .description("Manage open questions")
         .action(async (action, text) => {
         try {
             const ctx = await initContext();
@@ -1241,13 +1374,13 @@ export function registerMetaCommands(program) {
             }
             const sessionCtx = await loadSessionContext(ctx);
             // List questions
-            if (action === 'list') {
+            if (action === "list") {
                 output({ questions: sessionCtx.open_questions }, () => {
                     if (sessionCtx.open_questions.length === 0) {
-                        console.log(chalk.yellow('No open questions'));
+                        console.log(chalk.yellow("No open questions"));
                     }
                     else {
-                        console.log('Open questions:');
+                        console.log("Open questions:");
                         sessionCtx.open_questions.forEach((question, idx) => {
                             console.log(`  ${idx + 1}. ${question}`);
                         });
@@ -1256,16 +1389,16 @@ export function registerMetaCommands(program) {
                 return;
             }
             // Clear all questions
-            if (action === 'clear') {
+            if (action === "clear") {
                 sessionCtx.open_questions = [];
                 await saveSessionContext(ctx, sessionCtx);
-                output({ questions: [] }, () => success('Cleared all questions'));
+                output({ questions: [] }, () => success("Cleared all questions"));
                 return;
             }
             // Add question
-            if (action === 'add') {
+            if (action === "add") {
                 if (!text) {
-                    error('Question text is required for add action');
+                    error("Question text is required for add action");
                     process.exit(EXIT_CODES.ERROR);
                 }
                 sessionCtx.open_questions.push(text);
@@ -1274,13 +1407,15 @@ export function registerMetaCommands(program) {
                 return;
             }
             // Remove question by index (1-based)
-            if (action === 'remove') {
+            if (action === "remove") {
                 if (!text) {
-                    error('Index is required for remove action');
+                    error("Index is required for remove action");
                     process.exit(EXIT_CODES.ERROR);
                 }
                 const index = parseInt(text, 10);
-                if (isNaN(index) || index < 1 || index > sessionCtx.open_questions.length) {
+                if (Number.isNaN(index) ||
+                    index < 1 ||
+                    index > sessionCtx.open_questions.length) {
                     error(`Invalid index: ${text}. Must be between 1 and ${sessionCtx.open_questions.length}`);
                     process.exit(EXIT_CODES.ERROR);
                 }
@@ -1300,9 +1435,9 @@ export function registerMetaCommands(program) {
     });
     // meta-context-cmd: kspec meta context
     meta
-        .command('context')
-        .description('Show full session context')
-        .option('--clear', 'Clear all session context')
+        .command("context")
+        .description("Show full session context")
+        .option("--clear", "Clear all session context")
         .action(async (options) => {
         try {
             const ctx = await initContext();
@@ -1322,7 +1457,7 @@ export function registerMetaCommands(program) {
                     threads: [],
                     open_questions: [],
                     updated_at: sessionCtx.updated_at,
-                }, () => success('Cleared all session context'));
+                }, () => success("Cleared all session context"));
                 return;
             }
             // Show full session context
@@ -1332,38 +1467,38 @@ export function registerMetaCommands(program) {
                 open_questions: sessionCtx.open_questions,
                 updated_at: sessionCtx.updated_at,
             }, () => {
-                console.log(chalk.bold('Session Context'));
-                console.log(chalk.gray('─'.repeat(60)));
+                console.log(chalk.bold("Session Context"));
+                console.log(chalk.gray("─".repeat(60)));
                 // Focus
-                console.log(chalk.bold('\nFocus:'));
+                console.log(chalk.bold("\nFocus:"));
                 if (sessionCtx.focus) {
                     console.log(`  ${sessionCtx.focus}`);
                 }
                 else {
-                    console.log(chalk.gray('  (none)'));
+                    console.log(chalk.gray("  (none)"));
                 }
                 // Active threads
-                console.log(chalk.bold('\nActive Threads:'));
+                console.log(chalk.bold("\nActive Threads:"));
                 if (sessionCtx.threads.length > 0) {
                     sessionCtx.threads.forEach((thread, idx) => {
                         console.log(`  ${idx + 1}. ${thread}`);
                     });
                 }
                 else {
-                    console.log(chalk.gray('  (none)'));
+                    console.log(chalk.gray("  (none)"));
                 }
                 // Open questions
-                console.log(chalk.bold('\nOpen Questions:'));
+                console.log(chalk.bold("\nOpen Questions:"));
                 if (sessionCtx.open_questions.length > 0) {
                     sessionCtx.open_questions.forEach((question, idx) => {
                         console.log(`  ${idx + 1}. ${question}`);
                     });
                 }
                 else {
-                    console.log(chalk.gray('  (none)'));
+                    console.log(chalk.gray("  (none)"));
                 }
                 // Last updated
-                console.log(chalk.bold('\nLast Updated:'));
+                console.log(chalk.bold("\nLast Updated:"));
                 const updatedDate = new Date(sessionCtx.updated_at);
                 console.log(`  ${updatedDate.toISOString()}`);
                 console.log(chalk.gray(`  (${updatedDate.toLocaleString()})`));