@kynetic-ai/spec 0.1.2 → 0.3.0

package/dist/cli/commands/item.js

@@ -1,26 +1,31 @@
-import chalk from 'chalk';
-import { initContext, buildIndexes, createSpecItem, deleteSpecItem, updateSpecItem, addChildItem, loadAllItems, loadAllTasks, ReferenceIndex, AlignmentIndex, checkSlugUniqueness, patchSpecItems, findChildItems, findTraitImplementors, createNote, } from '../../parser/index.js';
-import { commitIfShadow } from '../../parser/shadow.js';
-import { SpecItemPatchSchema } from '../../schema/index.js';
-import { output, error, success, warn, isJsonMode } from '../output.js';
-import { grepItem, formatMatchedFields } from '../../utils/grep.js';
-import { errors } from '../../strings/errors.js';
-import { fieldLabels, sectionHeaders } from '../../strings/labels.js';
-import { EXIT_CODES } from '../exit-codes.js';
+import chalk from "chalk";
+import { markMutating } from "../command-annotations.js";
+import { AlignmentIndex, addChildItem, buildIndexes, checkSlugUniqueness, createNote, createSpecItem, deleteSpecItem, findChildItems, findDescendantItems, findTraitImplementors, initContext, loadAllItems, loadAllTasks, patchSpecItems, ReferenceIndex, updateSpecItem, } from "../../parser/index.js";
+import { commitIfShadow } from "../../parser/shadow.js";
+import { SpecItemPatchSchema } from "../../schema/index.js";
+import { errors } from "../../strings/errors.js";
+import { fieldLabels, sectionHeaders } from "../../strings/labels.js";
+import { formatMatchedFields, grepItem } from "../../utils/grep.js";
+import { EXIT_CODES } from "../exit-codes.js";
+import { error, isJsonMode, output, success, warn } from "../output.js";
+import { parseTagsArray } from "../parse-utils.js";
 /**
  * Format a spec item for display
  */
 function formatItem(item, verbose = false, grepPattern) {
     const shortId = item._ulid.slice(0, 8);
-    const slugStr = item.slugs.length > 0 ? chalk.cyan(`@${item.slugs[0]}`) : '';
+    const slugStr = item.slugs.length > 0 ? chalk.cyan(`@${item.slugs[0]}`) : "";
     const typeStr = chalk.gray(`[${item.type}]`);
-    let status = '';
-    if (item.status && typeof item.status === 'object') {
+    let status = "";
+    if (item.status && typeof item.status === "object") {
         const s = item.status;
         if (s.implementation) {
-            const implColor = s.implementation === 'verified' ? chalk.green
-                : s.implementation === 'implemented' ? chalk.cyan
-                    : s.implementation === 'in_progress' ? chalk.yellow
+            const implColor = s.implementation === "verified"
+                ? chalk.green
+                : s.implementation === "implemented"
+                    ? chalk.cyan
+                    : s.implementation === "in_progress"
+                        ? chalk.yellow
                         : chalk.gray;
             status = implColor(s.implementation);
         }
@@ -34,16 +39,18 @@ function formatItem(item, verbose = false, grepPattern) {
     if (status)
         line += ` ${status}`;
     if (verbose) {
-        const tags = 'tags' in item && Array.isArray(item.tags) ? item.tags : [];
+        const tags = "tags" in item && Array.isArray(item.tags) ? item.tags : [];
         if (tags.length > 0) {
-            line += chalk.blue(` #${tags.join(' #')}`);
+            line += chalk.blue(` #${tags.join(" #")}`);
         }
     }
     // Show matched fields if grep pattern provided
     if (grepPattern) {
         const match = grepItem(item, grepPattern);
         if (match && match.matchedFields.length > 0) {
-            line += '\n  ' + chalk.gray(`matched: ${formatMatchedFields(match.matchedFields)}`);
+            line +=
+                "\n  " +
+                    chalk.gray(`matched: ${formatMatchedFields(match.matchedFields)}`);
         }
     }
     return line;
@@ -53,7 +60,7 @@ function formatItem(item, verbose = false, grepPattern) {
  */
 function formatItemList(items, verbose = false, grepPattern) {
     if (items.length === 0) {
-        console.log(chalk.gray('No items found'));
+        console.log(chalk.gray("No items found"));
         return;
     }
     for (const item of items) {
@@ -66,37 +73,37 @@ function formatItemList(items, verbose = false, grepPattern) {
  */
 function formatItemTree(items, verbose = false, grepPattern) {
     if (items.length === 0) {
-        console.log(chalk.gray('No items found'));
+        console.log(chalk.gray("No items found"));
         return;
     }
     // Build parent-child map
     const childrenMap = new Map();
     const rootItems = [];
     for (const item of items) {
-        const path = item._path || '';
+        const path = item._path || "";
         // Determine parent path
-        let parentPath = '';
+        let parentPath = "";
         if (path) {
             // Extract parent path from current path
             // e.g., "features[0].requirements[1]" -> "features[0]"
-            const lastDotIndex = path.lastIndexOf('.');
+            const lastDotIndex = path.lastIndexOf(".");
             if (lastDotIndex !== -1) {
                 parentPath = path.substring(0, lastDotIndex);
             }
         }
-        if (parentPath === '') {
+        if (parentPath === "") {
             // Root level item
             rootItems.push(item);
         }
         else {
             // Find parent by path
-            const parent = items.find(i => i._path === parentPath);
+            const parent = items.find((i) => i._path === parentPath);
             if (parent) {
                 const parentUlid = parent._ulid;
                 if (!childrenMap.has(parentUlid)) {
                     childrenMap.set(parentUlid, []);
                 }
-                childrenMap.get(parentUlid).push(item);
+                childrenMap.get(parentUlid)?.push(item);
             }
             else {
                 // Parent not in filtered list, show at root
@@ -105,14 +112,14 @@ function formatItemTree(items, verbose = false, grepPattern) {
         }
     }
     // Recursive function to print tree
-    function printTree(item, prefix = '', isLast = true) {
+    function printTree(item, prefix = "", isLast = true) {
         // Print current item with tree prefix
-        const connector = isLast ? '└── ' : '├── ';
+        const connector = isLast ? "└── " : "├── ";
         const itemLine = formatItem(item, verbose, grepPattern);
         console.log(prefix + connector + itemLine);
         // Print children
         const children = childrenMap.get(item._ulid) || [];
-        const childPrefix = prefix + (isLast ? '    ' : '│   ');
+        const childPrefix = prefix + (isLast ? "    " : "│   ");
         children.forEach((child, index) => {
             const isLastChild = index === children.length - 1;
             printTree(child, childPrefix, isLastChild);
@@ -121,7 +128,7 @@ function formatItemTree(items, verbose = false, grepPattern) {
     // Print all root items
     rootItems.forEach((item, index) => {
         const isLast = index === rootItems.length - 1;
-        printTree(item, '', isLast);
+        printTree(item, "", isLast);
     });
     console.log(chalk.gray(`\n${items.length} item(s)`));
 }
@@ -140,7 +147,7 @@ async function handleStatusCascade(ctx, parent, newStatus, allItems, refIndex) {
         return [];
     }
     // Prompt user for cascade
-    const readline = await import('readline');
+    const readline = await import("node:readline");
     const rl = readline.createInterface({
         input: process.stdin,
         output: process.stdout,
@@ -149,18 +156,21 @@ async function handleStatusCascade(ctx, parent, newStatus, allItems, refIndex) {
         rl.question(`Update ${children.length} child item(s) to ${newStatus}? [y/n] `, resolve);
     });
     rl.close();
-    if (answer.toLowerCase() !== 'y') {
+    if (answer.toLowerCase() !== "y") {
         return [];
     }
     // Update children
     const updatedChildren = [];
     for (const child of children) {
-        const currentStatus = child.status && typeof child.status === 'object'
+        const currentStatus = child.status && typeof child.status === "object"
             ? child.status
-            : { maturity: 'draft', implementation: 'not_started' };
+            : {
+                maturity: "draft",
+                implementation: "not_started",
+            };
         const updates = {
             status: {
-                maturity: currentStatus.maturity || 'draft',
+                maturity: currentStatus.maturity || "draft",
                 implementation: newStatus,
             },
         };
@@ -176,27 +186,27 @@ async function handleStatusCascade(ctx, parent, newStatus, allItems, refIndex) {
  * Register item commands
  */
 export function registerItemCommands(program) {
-    const item = program
-        .command('item')
-        .description('Spec item commands');
+    const item = program.command("item").description("Spec item commands");
     // kspec item list
     item
-        .command('list')
-        .description('List spec items with optional filters')
-        .option('-t, --type <type>', 'Filter by item type (module, feature, requirement, constraint, decision)')
-        .option('-s, --status <status>', 'Filter by implementation status (not_started, in_progress, implemented, verified)')
-        .option('-m, --maturity <maturity>', 'Filter by maturity (draft, proposed, stable, deferred, deprecated)')
-        .option('--tag <tag>', 'Filter by tag (can specify multiple)', (val, prev) => [...prev, val], [])
-        .option('--has <field>', 'Filter items that have field present', (val, prev) => [...prev, val], [])
-        .option('-q, --search <text>', 'Search in title')
-        .option('-g, --grep <pattern>', 'Search content with regex pattern')
-        .option('-v, --verbose', 'Show more details')
-        .option('--tree', 'Show parent/child hierarchy')
-        .option('--limit <n>', 'Limit results', '50')
+        .command("list")
+        .description("List spec items with optional filters")
+        .option("-t, --type <type>", "Filter by item type (module, feature, requirement, constraint, decision)")
+        .option("-s, --status <status>", "Filter by implementation status (not_started, in_progress, implemented, verified)")
+        .option("-m, --maturity <maturity>", "Filter by maturity (draft, proposed, stable, deferred, deprecated)")
+        .option("--tag <tag>", "Filter by tag (can specify multiple)", (val, prev) => [...prev, val], [])
+        .option("--has <field>", "Filter items that have field present", (val, prev) => [...prev, val], [])
+        .option("-q, --search <text>", "Search in title")
+        .option("-g, --grep <pattern>", "Search content with regex pattern")
+        .option("-v, --verbose", "Show more details")
+        .option("--tree", "Show parent/child hierarchy")
+        .option("--under <ref>", "Scope to descendants of a module or parent item")
+        .option("--limit <n>", "Limit results", "50")
+        .option("--count", "Show only the count of matching items")
         .action(async (options) => {
         try {
             const ctx = await initContext();
-            const { itemIndex, items } = await buildIndexes(ctx);
+            const { itemIndex, items, refIndex } = await buildIndexes(ctx);
             // Build filter from options
             const filter = {
                 specItemsOnly: true, // Only spec items, not tasks
@@ -204,14 +214,20 @@ export function registerItemCommands(program) {
             if (options.type) {
                 filter.type = options.type;
             }
+            // AC: @multi-value-status-filter ac-item-list-parity, ac-invalid-item-status
             if (options.status) {
-                filter.implementation = options.status;
+                const { parseMultiStatus } = await import("./tasks.js");
+                const { ImplementationStatusSchema } = await import("../../schema/common.js");
+                const statuses = parseMultiStatus(options.status, ImplementationStatusSchema.options, "implementation status");
+                if (statuses) {
+                    filter.implementation = statuses.length === 1 ? statuses[0] : statuses;
+                }
             }
             if (options.maturity) {
                 filter.maturity = options.maturity;
             }
             if (options.tag && options.tag.length > 0) {
-                filter.tags = options.tag;
+                filter.tags = parseTagsArray(options.tag);
             }
             if (options.has && options.has.length > 0) {
                 filter.hasFields = options.has;
@@ -222,18 +238,67 @@ export function registerItemCommands(program) {
             if (options.grep) {
                 filter.grepSearch = options.grep;
             }
+            // AC: @module-scoped-item-listing ac-under-filter, ac-under-invalid-ref
+            // Handle --under: scope to descendants of a module or parent item
+            let underRoot;
+            let underDescendantUlids;
+            if (options.under) {
+                const underResult = refIndex.resolve(options.under);
+                if (!underResult.ok) {
+                    // AC: @module-scoped-item-listing ac-under-invalid-ref
+                    error(`Reference not found: ${options.under}. Check with: kspec item get ${options.under}`);
+                    process.exit(EXIT_CODES.NOT_FOUND);
+                }
+                underRoot = underResult.item;
+                // Check it's not a task
+                if ("status" in underRoot && typeof underRoot.status === "string") {
+                    error(`Reference ${options.under} is a task, not a spec item`);
+                    process.exit(EXIT_CODES.USAGE_ERROR);
+                }
+                // AC: @module-scoped-item-listing ac-nested-descendants
+                // Find all descendants based on _path and _sourceFile
+                const descendants = findDescendantItems(underRoot, items);
+                underDescendantUlids = new Set([underRoot._ulid, ...descendants.map(d => d._ulid)]);
+            }
             const limit = parseInt(options.limit, 10) || 50;
-            const result = itemIndex.queryPaginated(filter, 0, limit);
-            // Filter to only LoadedSpecItem (not tasks)
-            const specItems = result.items.filter((item) => !('status' in item && typeof item.status === 'string'));
+            // When --under is used, we need to get all items first, then filter by scope,
+            // because pagination before scoping could miss items
+            let specItems;
+            let effectiveTotal;
+            if (underDescendantUlids) {
+                // AC: @module-scoped-item-listing ac-under-filter, ac-under-with-other-filters
+                // Get all items matching filters, then scope to descendants
+                const allResults = itemIndex.query(filter);
+                const allSpecItems = allResults.filter((item) => !("status" in item && typeof item.status === "string"));
+                // Apply --under filtering (AND logic with other filters)
+                const scopedItems = allSpecItems.filter(item => underDescendantUlids.has(item._ulid));
+                effectiveTotal = scopedItems.length;
+                specItems = scopedItems.slice(0, limit);
+            }
+            else {
+                const result = itemIndex.queryPaginated(filter, 0, limit);
+                // Filter to only LoadedSpecItem (not tasks)
+                specItems = result.items.filter((item) => !("status" in item && typeof item.status === "string"));
+                effectiveTotal = result.total;
+            }
+            // AC: @module-scoped-item-listing ac-count-with-under
+            // AC: @trait-filterable-list ac-8
+            if (options.count) {
+                output({ count: effectiveTotal }, () => {
+                    console.log(effectiveTotal);
+                });
+                return;
+            }
             output({
                 items: specItems,
-                total: result.total,
+                total: effectiveTotal,
                 showing: specItems.length,
                 grepPattern: options.grep,
                 tree: options.tree,
+                under: options.under,
             }, () => {
                 if (options.tree) {
+                    // AC: @module-scoped-item-listing ac-under-with-tree
                     formatItemTree(specItems, options.verbose, options.grep);
                 }
                 else {
@@ -248,8 +313,8 @@ export function registerItemCommands(program) {
     });
     // kspec item get <ref>
     item
-        .command('get <ref>')
-        .description('Get details for a specific item')
+        .command("get <ref>")
+        .description("Get details for a specific item")
         .action(async (ref) => {
         try {
             const ctx = await initContext();
@@ -267,7 +332,7 @@ export function registerItemCommands(program) {
                 if (!traitsByTrait.has(trait.ulid)) {
                     traitsByTrait.set(trait.ulid, { trait, acs: [] });
                 }
-                traitsByTrait.get(trait.ulid).acs.push(ac);
+                traitsByTrait.get(trait.ulid)?.acs.push(ac);
             }
             // Build JSON output with inherited traits
             const jsonOutput = {
@@ -280,31 +345,62 @@ export function registerItemCommands(program) {
             };
             output(jsonOutput, () => {
                 console.log(chalk.bold(item.title));
-                console.log(chalk.gray('─'.repeat(40)));
+                console.log(chalk.gray("─".repeat(40)));
                 console.log(`${fieldLabels.ulid}      ${item._ulid}`);
                 if (item.slugs.length > 0) {
-                    console.log(`${fieldLabels.slugs}     ${item.slugs.join(', ')}`);
+                    console.log(`${fieldLabels.slugs}     ${item.slugs.join(", ")}`);
                 }
                 console.log(`${fieldLabels.type}      ${item.type}`);
-                if (item.status && typeof item.status === 'object') {
+                if (item.status && typeof item.status === "object") {
                     const s = item.status;
                     if (s.maturity)
                         console.log(`${fieldLabels.maturity}  ${s.maturity}`);
-                    if (s.implementation)
-                        console.log(`${fieldLabels.implementation}${s.implementation}`);
+                    if (s.implementation) {
+                        // AC: @trait-retrospective ac-4
+                        // Show retrospective verification source
+                        const isRetrospective = item.traits?.includes("@trait-retrospective");
+                        const statusLabel = isRetrospective
+                            ? `${s.implementation} (retrospective)`
+                            : s.implementation;
+                        console.log(`${fieldLabels.implementation}${statusLabel}`);
+                    }
+                }
+                // AC: @trait-retrospective ac-4
+                // Show verification metadata for retrospective specs
+                const isRetrospective = item.traits?.includes("@trait-retrospective");
+                if (isRetrospective && (item.verified_at || item.verified_by)) {
+                    const verifiedDate = item.verified_at
+                        ? new Date(item.verified_at).toISOString().split("T")[0]
+                        : "unknown";
+                    const verifiedBy = item.verified_by || "unknown";
+                    console.log(`Verified:   ${verifiedDate} by ${verifiedBy}`);
+                }
+                if ("tags" in item &&
+                    Array.isArray(item.tags) &&
+                    item.tags.length > 0) {
+                    console.log(`${fieldLabels.tags}      ${item.tags.join(", ")}`);
+                }
+                // AC: @item-get ac-4
+                if (Array.isArray(item.depends_on) && item.depends_on.length > 0) {
+                    console.log(`${fieldLabels.dependsOn} ${item.depends_on.join(", ")}`);
                 }
-                if ('tags' in item && Array.isArray(item.tags) && item.tags.length > 0) {
-                    console.log(`${fieldLabels.tags}      ${item.tags.join(', ')}`);
+                if (Array.isArray(item.implements) && item.implements.length > 0) {
+                    console.log(`${fieldLabels.implements} ${item.implements.join(", ")}`);
+                }
+                if (Array.isArray(item.relates_to) && item.relates_to.length > 0) {
+                    console.log(`${fieldLabels.relatesTo} ${item.relates_to.join(", ")}`);
                 }
                 if (item.description) {
-                    console.log('\n' + sectionHeaders.description);
+                    console.log(`\n${sectionHeaders.description}`);
                     console.log(item.description);
                 }
                 // AC: @trait-display ac-1 - Show own AC first
-                if ('acceptance_criteria' in item && Array.isArray(item.acceptance_criteria) && item.acceptance_criteria.length > 0) {
-                    console.log('\n' + sectionHeaders.acceptanceCriteria);
+                if ("acceptance_criteria" in item &&
+                    Array.isArray(item.acceptance_criteria) &&
+                    item.acceptance_criteria.length > 0) {
+                    console.log(`\n${sectionHeaders.acceptanceCriteria}`);
                     for (const ac of item.acceptance_criteria) {
-                        if (ac && typeof ac === 'object' && 'id' in ac) {
+                        if (ac && typeof ac === "object" && "id" in ac) {
                             const acObj = ac;
                             console.log(chalk.cyan(`  [${acObj.id}]`));
                             if (acObj.given)
@@ -321,7 +417,8 @@ export function registerItemCommands(program) {
                     for (const { trait, acs } of traitsByTrait.values()) {
                         console.log(chalk.gray(`\n─── Inherited from @${trait.slug} ───`));
                         for (const ac of acs) {
-                            console.log(chalk.cyan(`  [${ac.id}]`) + chalk.gray(` (from @${trait.slug})`));
+                            console.log(chalk.cyan(`  [${ac.id}]`) +
+                                chalk.gray(` (from @${trait.slug})`));
                             if (ac.given)
                                 console.log(`    Given: ${ac.given}`);
                             if (ac.when)
@@ -340,16 +437,16 @@ export function registerItemCommands(program) {
     });
     // kspec item types - show available types and counts
     item
-        .command('types')
-        .description('Show item types and counts')
+        .command("types")
+        .description("Show item types and counts")
         .action(async () => {
         try {
             const ctx = await initContext();
             const { itemIndex } = await buildIndexes(ctx);
             const typeCounts = itemIndex.getTypeCounts();
             output(Object.fromEntries(typeCounts), () => {
-                console.log(chalk.bold('Item Types'));
-                console.log(chalk.gray('─'.repeat(30)));
+                console.log(chalk.bold("Item Types"));
+                console.log(chalk.gray("─".repeat(30)));
                 for (const [type, count] of typeCounts) {
                     console.log(`  ${type}: ${count}`);
                 }
@@ -363,16 +460,16 @@ export function registerItemCommands(program) {
     });
     // kspec item tags - show available tags and counts
     item
-        .command('tags')
-        .description('Show tags and counts')
+        .command("tags")
+        .description("Show tags and counts")
         .action(async () => {
         try {
             const ctx = await initContext();
             const { itemIndex } = await buildIndexes(ctx);
             const tagCounts = itemIndex.getTagCounts();
             output(Object.fromEntries(tagCounts), () => {
-                console.log(chalk.bold('Tags'));
-                console.log(chalk.gray('─'.repeat(30)));
+                console.log(chalk.bold("Tags"));
+                console.log(chalk.gray("─".repeat(30)));
                 for (const [tag, count] of tagCounts) {
                     console.log(`  #${tag}: ${count}`);
                 }
@@ -384,17 +481,22 @@ export function registerItemCommands(program) {
         }
     });
     // kspec item add - create a new spec item under a parent
-    item
-        .command('add')
-        .description('Create a new spec item under a parent')
-        .requiredOption('--under <ref>', 'Parent item reference (e.g., @core-primitives)')
-        .requiredOption('--title <title>', 'Item title')
-        .option('--type <type>', 'Item type (feature, requirement, constraint, decision)', 'feature')
-        .option('--slug <slug>', 'Human-friendly slug')
-        .option('--priority <priority>', 'Priority (high, medium, low)')
-        .option('--tag <tag...>', 'Tags')
-        .option('--description <desc>', 'Description')
-        .option('--as <field>', 'Child field override (e.g., requirements, constraints)')
+    markMutating(item.command("add"))
+        .description("Create a new spec item under a parent")
+        .requiredOption("--under <ref>", "Parent item reference (e.g., @core-primitives)")
+        .requiredOption("--title <title>", "Item title")
+        .option("--type <type>", "Item type (feature, requirement, constraint, decision)", "feature")
+        .option("--slug <slug>", "Human-friendly slug")
+        .option("--priority <priority>", "Priority (high, medium, low)")
+        .option("--tag <tag...>", "Tags")
+        .option("--trait <trait...>", "Traits to apply (e.g., @trait-testable)")
+        .option("--description <desc>", "Description")
+        .option("--as <field>", "Child field override (e.g., requirements, constraints)")
+        .addHelpText("after", `
+Examples:
+  $ kspec item add --under @parent --title "Feature name" --type feature
+  $ kspec item add --under @parent --title "Multi-tag" --tag api public
+  $ kspec item add --under @parent --title "API endpoint" --trait @trait-api-endpoint`)
         .action(async (options) => {
         try {
             const ctx = await initContext();
@@ -407,7 +509,7 @@ export function registerItemCommands(program) {
             }
             const parent = parentResult.item;
             // Check it's not a task
-            if ('status' in parent && typeof parent.status === 'string') {
+            if ("status" in parent && typeof parent.status === "string") {
                 error(errors.reference.parentIsTask(options.under));
                 process.exit(EXIT_CODES.ERROR);
             }
@@ -419,33 +521,66 @@ export function registerItemCommands(program) {
                     process.exit(EXIT_CODES.CONFLICT);
                 }
             }
+            // Validate and canonicalize traits
+            const validatedTraits = [];
+            const seenTraitUlids = new Set();
+            let hasTraitErrors = false;
+            if (options.trait) {
+                for (const traitRef of options.trait) {
+                    const traitResult = refIndex.resolve(traitRef);
+                    if (!traitResult.ok) {
+                        error(`Trait not found: ${traitRef}`);
+                        hasTraitErrors = true;
+                        continue;
+                    }
+                    const traitItem = traitResult.item;
+                    if (traitItem.type !== "trait") {
+                        error(`${traitRef} is not a trait (type: ${traitItem.type})`);
+                        hasTraitErrors = true;
+                        continue;
+                    }
+                    // Deduplicate by ULID
+                    if (seenTraitUlids.has(traitItem._ulid)) {
+                        continue;
+                    }
+                    seenTraitUlids.add(traitItem._ulid);
+                    // Store canonical ref (prefer slug over ULID)
+                    const canonicalRef = `@${traitItem.slugs[0] || traitItem._ulid}`;
+                    validatedTraits.push(canonicalRef);
+                }
+            }
+            if (hasTraitErrors) {
+                process.exit(EXIT_CODES.NOT_FOUND);
+            }
             const input = {
                 title: options.title,
                 type: options.type,
                 slugs: options.slug ? [options.slug] : [],
                 priority: options.priority,
-                tags: options.tag || [],
+                tags: parseTagsArray(options.tag),
                 description: options.description,
                 depends_on: [],
                 implements: [],
                 relates_to: [],
                 tests: [],
-                traits: [],
+                traits: validatedTraits,
                 notes: [],
             };
             const newItem = createSpecItem(input);
             const result = await addChildItem(ctx, parent, newItem, options.as);
             // Build index including the new item for accurate short ULID
             const index = new ReferenceIndex([], [...items, result.item]);
-            const itemSlug = result.item.slugs?.[0] || index.shortUlid(result.item._ulid);
-            await commitIfShadow(ctx.shadow, 'item-add', itemSlug);
+            const itemSlug = result.item.slugs?.[0] ||
+                index.shortUlid(result.item._ulid);
+            await commitIfShadow(ctx.shadow, "item-add", itemSlug);
             success(`Created item: ${index.shortUlid(result.item._ulid)} under @${parent.slugs[0] || parent._ulid.slice(0, 8)}`, {
                 item: result.item,
                 path: result.path,
             });
             // Derive hint
             if (!isJsonMode()) {
-                const refSlug = result.item.slugs?.[0] || index.shortUlid(result.item._ulid);
+                const refSlug = result.item.slugs?.[0] ||
+                    index.shortUlid(result.item._ulid);
                 console.log(chalk.gray(`\nDerive implementation task? kspec derive @${refSlug}`));
             }
         }
@@ -455,22 +590,38 @@ export function registerItemCommands(program) {
         }
     });
     // kspec item set - update a spec item field
-    item
-        .command('set <ref>')
-        .description('Update a spec item field')
-        .option('--title <title>', 'Set title')
-        .option('--type <type>', 'Set type')
-        .option('--slug <slug>', 'Add a slug')
-        .option('--remove-slug <slug>', 'Remove a slug')
-        .option('--priority <priority>', 'Set priority')
-        .option('--tag <tag...>', 'Set tags (replaces existing)')
-        .option('--description <desc>', 'Set description')
-        .option('--status <status>', 'Set implementation status (not_started, in_progress, implemented, verified)')
-        .option('--maturity <maturity>', 'Set maturity (draft, proposed, stable, deferred, deprecated)')
+    markMutating(item.command("set <ref>"))
+        .description("Update a spec item field")
+        .option("--title <title>", "Set title")
+        .option("--type <type>", "Set type")
+        .option("--slug <slug>", "Add a slug")
+        .option("--remove-slug <slug>", "Remove a slug")
+        .option("--priority <priority>", "Set priority")
+        .option("--tag <tag...>", "Set tags (replaces existing)")
+        .option("--description <desc>", "Set description")
+        .option("--status <status>", "Set implementation status (not_started, in_progress, implemented, verified)")
+        .option("--maturity <maturity>", "Set maturity (draft, proposed, stable, deferred, deprecated)")
+        .option("--verified-by <agent-ref>", "Set verified_by (for retrospective specs)")
+        .option("--verified-at <iso-timestamp>", "Set verified_at (defaults to now if --verified-by provided)")
+        .option("--trait <trait...>", "Set traits (replaces existing)")
+        .option("--relates-to <ref>", "Add a relates_to reference")
+        .option("--implements <ref>", "Add an implements reference")
+        .option("--depends-on <ref>", "Add a depends_on reference")
+        .option("--clear-relates-to", "Clear all relates_to references")
+        .option("--clear-implements", "Clear all implements references")
+        .option("--clear-depends-on", "Clear all depends_on references")
+        .addHelpText("after", `
+Examples:
+  $ kspec item set @item-ref --title "New title"
+  $ kspec item set @item-ref --tag api internal security
+  $ kspec item set @item-ref --trait reusable testable
+  $ kspec item set @item-ref --relates-to @other-item
+  $ kspec item set @item-ref --implements @feature-spec
+  $ kspec item set @item-ref --depends-on @prereq-spec`)
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
-            const { refIndex, items } = await buildIndexes(ctx);
+            const { refIndex, items, tasks } = await buildIndexes(ctx);
             const result = refIndex.resolve(ref);
             if (!result.ok) {
                 error(errors.reference.itemNotFound(ref));
@@ -478,7 +629,7 @@ export function registerItemCommands(program) {
             }
             const foundItem = result.item;
             // Check if it's a task (tasks should use task commands)
-            if ('status' in foundItem && typeof foundItem.status === 'string') {
+            if ("status" in foundItem && typeof foundItem.status === "string") {
                 error(errors.reference.taskUseTaskCommands(ref));
                 process.exit(EXIT_CODES.ERROR);
             }
@@ -502,6 +653,66 @@ export function registerItemCommands(program) {
                     process.exit(EXIT_CODES.ERROR);
                 }
             }
+            // Mutual exclusivity: cannot add and clear same field
+            // Check this before ref resolution so usage errors take precedence
+            if (options.relatesTo && options.clearRelatesTo) {
+                error("Cannot use --relates-to and --clear-relates-to together");
+                process.exit(EXIT_CODES.USAGE_ERROR);
+            }
+            if (options.implements && options.clearImplements) {
+                error("Cannot use --implements and --clear-implements together");
+                process.exit(EXIT_CODES.USAGE_ERROR);
+            }
+            if (options.dependsOn && options.clearDependsOn) {
+                error("Cannot use --depends-on and --clear-depends-on together");
+                process.exit(EXIT_CODES.USAGE_ERROR);
+            }
+            // Helper to validate relationship refs (must exist and be a spec item, not a task)
+            // Returns { ulid, canonicalRef } for deduplication and user-friendly storage
+            const validateRelationshipRef = (refStr, flagName) => {
+                const refResult = refIndex.resolve(refStr);
+                if (!refResult.ok) {
+                    error(errors.reference.itemNotFound(refStr));
+                    process.exit(EXIT_CODES.NOT_FOUND);
+                }
+                // Ensure it's a spec item, not a task
+                const isTask = tasks.some((t) => t._ulid === refResult.ulid);
+                if (isTask) {
+                    error(`${flagName} reference must be a spec item, not a task: ${refStr}`);
+                    process.exit(EXIT_CODES.USAGE_ERROR);
+                }
+                // Use primary slug if available for user-friendly storage, otherwise ULID
+                const item = refResult.item;
+                const canonicalRef = item.slugs?.[0] ? `@${item.slugs[0]}` : `@${refResult.ulid}`;
+                return { ulid: refResult.ulid, canonicalRef };
+            };
+            // Helper to resolve existing refs to ULIDs for deduplication
+            const resolveRefsToUlids = (refs) => {
+                const ulids = new Set();
+                for (const ref of refs) {
+                    const result = refIndex.resolve(ref);
+                    if (result.ok) {
+                        ulids.add(result.ulid);
+                    }
+                }
+                return ulids;
+            };
+            // AC: @item-set ac-5 - --relates-to validation
+            // Store resolved ULID for deduplication and canonical ref for storage
+            let relatesToResolved;
+            if (options.relatesTo) {
+                relatesToResolved = validateRelationshipRef(options.relatesTo, "--relates-to");
+            }
+            // AC: @item-set ac-6 - --implements validation
+            let implementsResolved;
+            if (options.implements) {
+                implementsResolved = validateRelationshipRef(options.implements, "--implements");
+            }
+            // AC: @item-set ac-7 - --depends-on validation
+            let dependsOnResolved;
+            if (options.dependsOn) {
+                dependsOnResolved = validateRelationshipRef(options.dependsOn, "--depends-on");
+            }
             // Build updates object
             const updates = {};
             if (options.title)
@@ -511,7 +722,7 @@ export function registerItemCommands(program) {
             if (options.slug || options.removeSlug) {
                 let slugs = [...(foundItem.slugs || [])];
                 if (options.removeSlug) {
-                    slugs = slugs.filter(s => s !== options.removeSlug);
+                    slugs = slugs.filter((s) => s !== options.removeSlug);
                 }
                 if (options.slug) {
                     slugs.push(options.slug);
@@ -521,12 +732,14 @@ export function registerItemCommands(program) {
             if (options.priority)
                 updates.priority = options.priority;
             if (options.tag)
-                updates.tags = options.tag;
+                updates.tags = parseTagsArray(options.tag);
+            if (options.trait)
+                updates.traits = options.trait;
             if (options.description)
                 updates.description = options.description;
             // Handle status updates
             if (options.status || options.maturity) {
-                const currentStatus = foundItem.status && typeof foundItem.status === 'object'
+                const currentStatus = foundItem.status && typeof foundItem.status === "object"
                     ? foundItem.status
                     : {};
                 updates.status = {
@@ -535,8 +748,53 @@ export function registerItemCommands(program) {
                     ...(options.maturity && { maturity: options.maturity }),
                 };
             }
+            // Handle verification metadata (for retrospective specs)
+            if (options.verifiedBy) {
+                updates.verified_by = options.verifiedBy;
+                // Default verified_at to now if not specified
+                updates.verified_at = options.verifiedAt || new Date().toISOString();
+            }
+            else if (options.verifiedAt) {
+                updates.verified_at = options.verifiedAt;
+            }
+            // AC: @item-set ac-5 - Handle relates_to (append semantics)
+            // Uses resolved ULIDs for deduplication and stores canonical slug format
+            if (relatesToResolved) {
+                const current = foundItem.relates_to || [];
+                const existingUlids = resolveRefsToUlids(current);
+                if (!existingUlids.has(relatesToResolved.ulid)) {
+                    updates.relates_to = [...current, relatesToResolved.canonicalRef];
+                }
+            }
+            if (options.clearRelatesTo) {
+                updates.relates_to = [];
+            }
+            // AC: @item-set ac-6 - Handle implements (append semantics)
+            // Uses resolved ULIDs for deduplication and stores canonical slug format
+            if (implementsResolved) {
+                const current = foundItem.implements || [];
+                const existingUlids = resolveRefsToUlids(current);
+                if (!existingUlids.has(implementsResolved.ulid)) {
+                    updates.implements = [...current, implementsResolved.canonicalRef];
+                }
+            }
+            if (options.clearImplements) {
+                updates.implements = [];
+            }
+            // AC: @item-set ac-7 - Handle depends_on (append semantics)
+            // Uses resolved ULIDs for deduplication and stores canonical slug format
+            if (dependsOnResolved) {
+                const current = foundItem.depends_on || [];
+                const existingUlids = resolveRefsToUlids(current);
+                if (!existingUlids.has(dependsOnResolved.ulid)) {
+                    updates.depends_on = [...current, dependsOnResolved.canonicalRef];
+                }
+            }
+            if (options.clearDependsOn) {
+                updates.depends_on = [];
+            }
             if (Object.keys(updates).length === 0) {
-                warn('No updates specified');
+                warn("No updates specified");
                 return;
             }
             const updated = await updateSpecItem(ctx, foundItem, updates);
@@ -547,8 +805,10 @@ export function registerItemCommands(program) {
                 const cascadeResult = await handleStatusCascade(ctx, updated, options.status, items, refIndex);
                 updatedItems.push(...cascadeResult);
             }
-            await commitIfShadow(ctx.shadow, 'item-set', itemSlug);
-            success(`Updated item: ${refIndex.shortUlid(updated._ulid)}`, { item: updated });
+            await commitIfShadow(ctx.shadow, "item-set", itemSlug);
+            success(`Updated item: ${refIndex.shortUlid(updated._ulid)}`, {
+                item: updated,
+            });
             // Derive hint
             if (!isJsonMode()) {
                 const refSlug = updated.slugs?.[0] || refIndex.shortUlid(updated._ulid);
@@ -561,11 +821,10 @@ export function registerItemCommands(program) {
         }
     });
     // kspec item delete - delete a spec item
-    item
-        .command('delete <ref>')
-        .description('Delete a spec item (including nested items)')
-        .option('--force', 'Skip confirmation')
-        .option('--cascade', 'Delete item and all descendants')
+    markMutating(item.command("delete <ref>"))
+        .description("Delete a spec item (including nested items)")
+        .option("--force", "Skip confirmation")
+        .option("--cascade", "Delete item and all descendants")
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
@@ -577,7 +836,7 @@ export function registerItemCommands(program) {
             }
             const foundItem = result.item;
             // Check if it's a task
-            if ('status' in foundItem && typeof foundItem.status === 'string') {
+            if ("status" in foundItem && typeof foundItem.status === "string") {
                 error(errors.reference.itemUseTaskCancel(ref));
                 process.exit(EXIT_CODES.ERROR);
             }
@@ -585,15 +844,17 @@ export function registerItemCommands(program) {
                 error(errors.operation.cannotDeleteNoSource);
                 process.exit(EXIT_CODES.ERROR);
             }
-            // AC-7: Check if this is a trait with implementors
+            // AC: @spec-item-delete-children ac-7 - Check if this is a trait with implementors
             const implementors = findTraitImplementors(foundItem, items);
             if (implementors.length > 0) {
-                const implementorRefs = implementors.map(i => `@${i.slugs[0] || i._ulid.slice(0, 8)}`).join(', ');
+                const implementorRefs = implementors
+                    .map((i) => `@${i.slugs[0] || i._ulid.slice(0, 8)}`)
+                    .join(", ");
                 const errorMsg = `Cannot delete: trait is used by ${implementors.length} specs. Remove trait from specs first: ${implementorRefs}`;
                 if (isJsonMode()) {
                     error(errorMsg, {
-                        error: 'trait_in_use',
-                        implementors: implementors.map(i => ({
+                        error: "trait_in_use",
+                        implementors: implementors.map((i) => ({
                             ulid: i._ulid,
                             slug: i.slugs[0],
                             title: i.title,
@@ -605,16 +866,16 @@ export function registerItemCommands(program) {
                 }
                 process.exit(EXIT_CODES.ERROR);
             }
-            // AC-1/AC-8: Check for child items (nested YAML items, not relates_to refs)
+            // AC: @spec-item-delete-children ac-1 ac-8 - Check for child items (nested YAML items, not relates_to refs)
             const children = findChildItems(foundItem, items);
             if (children.length > 0 && !options.cascade) {
-                // AC-1: Block deletion if children exist without --cascade
+                // AC: @spec-item-delete-children ac-1 - Block deletion if children exist without --cascade
                 const errorMsg = `Cannot delete: item has ${children.length} children. Use --cascade to delete recursively`;
                 if (isJsonMode()) {
-                    // AC-10: JSON error includes children array
+                    // AC: @spec-item-delete-children ac-10 - JSON error includes children array
                     error(errorMsg, {
-                        error: 'has_children',
-                        children: children.map(c => ({
+                        error: "has_children",
+                        children: children.map((c) => ({
                             ulid: c._ulid,
                             slug: c.slugs[0],
                             title: c.title,
@@ -627,44 +888,46 @@ export function registerItemCommands(program) {
                 }
                 process.exit(EXIT_CODES.ERROR);
             }
-            // AC-9: Custom confirmation prompt for cascade
+            // AC: @spec-item-delete-children ac-9 - Custom confirmation prompt for cascade
             if (children.length > 0 && options.cascade && !options.force) {
                 const itemRef = `@${foundItem.slugs[0] || foundItem._ulid.slice(0, 8)}`;
                 // Check for JSON mode - requires --force
                 if (isJsonMode()) {
-                    error('Confirmation required. Use --force with --json');
+                    error("Confirmation required. Use --force with --json");
                     process.exit(EXIT_CODES.ERROR);
                 }
                 // Check for non-interactive environment
-                const isTTY = process.env.KSPEC_TEST_TTY === 'true' || process.stdin.isTTY;
+                const isTTY = process.env.KSPEC_TEST_TTY === "true" || process.stdin.isTTY;
                 if (!isTTY) {
-                    error('Non-interactive environment. Use --force to proceed');
+                    error("Non-interactive environment. Use --force to proceed");
                     process.exit(EXIT_CODES.ERROR);
                 }
                 // Show confirmation prompt
-                const readline = await import('readline');
+                const readline = await import("node:readline");
                 const rl = readline.createInterface({
                     input: process.stdin,
                     output: process.stdout,
                 });
-                const response = await new Promise(resolve => {
-                    rl.question(chalk.yellow(`Delete ${itemRef} and ${children.length} descendant items? [y/N] `), answer => {
+                const response = await new Promise((resolve) => {
+                    rl.question(chalk.yellow(`Delete ${itemRef} and ${children.length} descendant items? [y/N] `), (answer) => {
                         rl.close();
                         resolve(answer);
                     });
                 });
-                if (response.toLowerCase() !== 'y') {
-                    console.log(chalk.gray('Operation cancelled'));
+                if (response.toLowerCase() !== "y") {
+                    console.log(chalk.gray("Operation cancelled"));
                     process.exit(EXIT_CODES.USAGE_ERROR);
                 }
             }
-            // AC-2/AC-3: Delete item and all descendants with cascade
-            const itemsToDelete = options.cascade ? [foundItem, ...children] : [foundItem];
+            // AC: @spec-item-delete-children ac-2 ac-3 - Delete item and all descendants with cascade
+            const itemsToDelete = options.cascade
+                ? [foundItem, ...children]
+                : [foundItem];
             let deletedCount = 0;
             // Delete in reverse order (deepest first) to avoid path issues
             const sortedItems = [...itemsToDelete].sort((a, b) => {
-                const aDepth = a._path ? a._path.split('.').length : 0;
-                const bDepth = b._path ? b._path.split('.').length : 0;
+                const aDepth = a._path ? a._path.split(".").length : 0;
+                const bDepth = b._path ? b._path.split(".").length : 0;
                 return bDepth - aDepth;
             });
             for (const itemToDelete of sortedItems) {
@@ -674,20 +937,26 @@ export function registerItemCommands(program) {
                 }
             }
             if (deletedCount > 0) {
-                // AC-6: Single shadow commit with all deletions
+                // AC: @spec-item-delete-children ac-6 - Single shadow commit with all deletions
                 const itemSlug = foundItem.slugs[0] || refIndex.shortUlid(foundItem._ulid);
                 const commitMsg = deletedCount > 1 ? `${deletedCount} items` : itemSlug;
-                await commitIfShadow(ctx.shadow, 'item-delete', commitMsg);
+                await commitIfShadow(ctx.shadow, "item-delete", commitMsg);
                 if (deletedCount > 1) {
-                    success(`Deleted ${deletedCount} items`, { deleted: deletedCount, root_ulid: foundItem._ulid });
+                    success(`Deleted ${deletedCount} items`, {
+                        deleted: deletedCount,
+                        root_ulid: foundItem._ulid,
+                    });
                 }
                 else {
-                    success(`Deleted item: ${foundItem.title}`, { deleted: true, ulid: foundItem._ulid });
+                    success(`Deleted item: ${foundItem.title}`, {
+                        deleted: true,
+                        ulid: foundItem._ulid,
+                    });
                 }
             }
             else {
                 error(errors.failures.deleteItem);
-                console.log(chalk.gray('Edit the source file directly: ' + foundItem._sourceFile));
+                console.log(chalk.gray(`Edit the source file directly: ${foundItem._sourceFile}`));
                 process.exit(EXIT_CODES.ERROR);
             }
         }
@@ -697,14 +966,13 @@ export function registerItemCommands(program) {
         }
     });
     // kspec item patch - update item fields via JSON
-    item
-        .command('patch [ref]')
-        .description('Update spec item fields via JSON patch')
-        .option('--data <json>', 'JSON data to patch')
-        .option('--bulk', 'Read patches from stdin (JSONL or JSON array)')
-        .option('--allow-unknown', 'Allow fields not in schema')
-        .option('--dry-run', 'Preview changes without applying')
-        .option('--fail-fast', 'Stop on first error (bulk mode)')
+    markMutating(item.command("patch [ref]"))
+        .description("Update spec item fields via JSON patch")
+        .option("--data <json>", "JSON data to patch")
+        .option("--bulk", "Read patches from stdin (JSONL or JSON array)")
+        .option("--allow-unknown", "Allow fields not in schema")
+        .option("--dry-run", "Preview changes without applying")
+        .option("--fail-fast", "Stop on first error (bulk mode)")
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
@@ -735,7 +1003,7 @@ export function registerItemCommands(program) {
                 });
                 // Shadow commit if any updates
                 if (!options.dryRun && result.summary.updated > 0) {
-                    await commitIfShadow(ctx.shadow, 'item-patch', `${result.summary.updated} items`);
+                    await commitIfShadow(ctx.shadow, "item-patch", `${result.summary.updated} items`);
                 }
                 output(result, () => formatBulkPatchResult(result, options.dryRun));
                 if (result.summary.failed > 0) {
@@ -755,7 +1023,7 @@ export function registerItemCommands(program) {
                         data = JSON.parse(options.data);
                     }
                     catch (err) {
-                        error(errors.validation.invalidJsonInData(err instanceof Error ? err.message : ''));
+                        error(errors.validation.invalidJsonInData(err instanceof Error ? err.message : ""));
                         process.exit(EXIT_CODES.ERROR);
                     }
                 }
@@ -766,7 +1034,7 @@ export function registerItemCommands(program) {
                             data = JSON.parse(stdin.trim());
                         }
                         catch (err) {
-                            error(errors.validation.invalidJsonFromStdin(err instanceof Error ? err.message : ''));
+                            error(errors.validation.invalidJsonFromStdin(err instanceof Error ? err.message : ""));
                             process.exit(EXIT_CODES.ERROR);
                         }
                     }
@@ -781,7 +1049,9 @@ export function registerItemCommands(program) {
                     const strictSchema = SpecItemPatchSchema.strict();
                     const parseResult = strictSchema.safeParse(data);
                     if (!parseResult.success) {
-                        const issues = parseResult.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; ');
+                        const issues = parseResult.error.issues
+                            .map((i) => `${i.path.join(".")}: ${i.message}`)
+                            .join("; ");
                         error(errors.validation.invalidPatchDataWithIssues(issues));
                         process.exit(EXIT_CODES.ERROR);
                     }
@@ -794,23 +1064,28 @@ export function registerItemCommands(program) {
                     process.exit(EXIT_CODES.ERROR);
                 }
                 // Find the item
-                const foundItem = items.find(i => i._ulid === resolved.ulid);
+                const foundItem = items.find((i) => i._ulid === resolved.ulid);
                 if (!foundItem) {
                     error(errors.reference.notItem(ref));
                     process.exit(EXIT_CODES.ERROR);
                 }
                 if (options.dryRun) {
-                    output({ ref, data, wouldApplyTo: foundItem.title, ulid: foundItem._ulid }, () => {
-                        console.log(chalk.yellow('Would patch:'), foundItem.title);
-                        console.log(chalk.gray('ULID:'), foundItem._ulid.slice(0, 8));
-                        console.log(chalk.gray('Changes:'));
+                    output({
+                        ref,
+                        data,
+                        wouldApplyTo: foundItem.title,
+                        ulid: foundItem._ulid,
+                    }, () => {
+                        console.log(chalk.yellow("Would patch:"), foundItem.title);
+                        console.log(chalk.gray("ULID:"), foundItem._ulid.slice(0, 8));
+                        console.log(chalk.gray("Changes:"));
                         console.log(JSON.stringify(data, null, 2));
                     });
                     return;
                 }
                 const updated = await updateSpecItem(ctx, foundItem, data);
                 const itemSlug = foundItem.slugs[0] || refIndex.shortUlid(foundItem._ulid);
-                await commitIfShadow(ctx.shadow, 'item-patch', itemSlug);
+                await commitIfShadow(ctx.shadow, "item-patch", itemSlug);
                 success(`Patched item: ${itemSlug}`, { item: updated });
             }
         }
@@ -821,8 +1096,8 @@ export function registerItemCommands(program) {
     });
     // kspec item status - show implementation status with linked tasks
     item
-        .command('status <ref>')
-        .description('Show implementation status and linked tasks for a spec item')
+        .command("status <ref>")
+        .description("Show implementation status and linked tasks for a spec item")
         .action(async (ref) => {
         try {
             const ctx = await initContext();
@@ -836,7 +1111,7 @@ export function registerItemCommands(program) {
             }
             const foundItem = result.item;
             // Check if it's a task
-            if ('status' in foundItem && typeof foundItem.status === 'string') {
+            if ("status" in foundItem && typeof foundItem.status === "string") {
                 error(errors.reference.notItem(ref));
                 process.exit(EXIT_CODES.ERROR);
             }
@@ -850,34 +1125,40 @@ export function registerItemCommands(program) {
             }
             output(summary, () => {
                 console.log(chalk.bold(foundItem.title));
-                console.log(chalk.gray('─'.repeat(40)));
+                console.log(chalk.gray("─".repeat(40)));
                 // Status
-                const currentColor = summary.currentStatus === 'implemented' ? chalk.green
-                    : summary.currentStatus === 'in_progress' ? chalk.yellow
+                const currentColor = summary.currentStatus === "implemented"
+                    ? chalk.green
+                    : summary.currentStatus === "in_progress"
+                        ? chalk.yellow
                         : chalk.gray;
-                const expectedColor = summary.expectedStatus === 'implemented' ? chalk.green
-                    : summary.expectedStatus === 'in_progress' ? chalk.yellow
+                const expectedColor = summary.expectedStatus === "implemented"
+                    ? chalk.green
+                    : summary.expectedStatus === "in_progress"
+                        ? chalk.yellow
                         : chalk.gray;
                 console.log(`Current status:  ${currentColor(summary.currentStatus)}`);
                 console.log(`Expected status: ${expectedColor(summary.expectedStatus)}`);
                 if (!summary.isAligned) {
-                    console.log(chalk.yellow('\n⚠ Status mismatch - run task complete to sync'));
+                    console.log(chalk.yellow("\n⚠ Status mismatch - run task complete to sync"));
                 }
                 else {
-                    console.log(chalk.green('\n✓ Aligned'));
+                    console.log(chalk.green("\n✓ Aligned"));
                 }
                 // Linked tasks
-                console.log(chalk.bold('\nLinked Tasks:'));
+                console.log(chalk.bold("\nLinked Tasks:"));
                 if (summary.linkedTasks.length === 0) {
-                    console.log(chalk.gray('  No tasks reference this spec item'));
+                    console.log(chalk.gray("  No tasks reference this spec item"));
                 }
                 else {
                     for (const task of summary.linkedTasks) {
-                        const statusColor = task.taskStatus === 'completed' ? chalk.green
-                            : task.taskStatus === 'in_progress' ? chalk.blue
+                        const statusColor = task.taskStatus === "completed"
+                            ? chalk.green
+                            : task.taskStatus === "in_progress"
+                                ? chalk.blue
                                 : chalk.gray;
                         const shortId = task.taskUlid.slice(0, 8);
-                        const notes = task.hasNotes ? chalk.gray(' (has notes)') : '';
+                        const notes = task.hasNotes ? chalk.gray(" (has notes)") : "";
                         console.log(`  ${statusColor(`[${task.taskStatus}]`)} ${shortId} ${task.taskTitle}${notes}`);
                     }
                 }
@@ -889,11 +1170,10 @@ export function registerItemCommands(program) {
         }
     });
     // kspec item note <ref> <message>
-    item
-        .command('note <ref> <message>')
-        .description('Add a note to a spec item')
-        .option('--author <author>', 'Note author')
-        .option('--supersedes <ulid>', 'ULID of note this supersedes')
+    markMutating(item.command("note <ref> <message>"))
+        .description("Add a note to a spec item")
+        .option("--author <author>", "Note author")
+        .option("--supersedes <ulid>", "ULID of note this supersedes")
         .action(async (ref, message, options) => {
         try {
             const ctx = await initContext();
@@ -905,7 +1185,7 @@ export function registerItemCommands(program) {
                 error(errors.reference.itemNotFound(ref));
                 process.exit(EXIT_CODES.ERROR);
             }
-            const foundItem = items.find(i => i._ulid === result.ulid);
+            const foundItem = items.find((i) => i._ulid === result.ulid);
             if (!foundItem) {
                 error(errors.reference.itemNotFound(ref));
                 process.exit(EXIT_CODES.ERROR);
@@ -914,7 +1194,7 @@ export function registerItemCommands(program) {
             const updatedNotes = [...(foundItem.notes || []), note];
             await updateSpecItem(ctx, foundItem, { notes: updatedNotes });
             const itemSlug = foundItem.slugs[0] || refIndex.shortUlid(foundItem._ulid);
-            await commitIfShadow(ctx.shadow, 'item-note', itemSlug);
+            await commitIfShadow(ctx.shadow, "item-note", itemSlug);
             success(`Added note to spec item: ${refIndex.shortUlid(foundItem._ulid)}`, { note });
         }
         catch (err) {
@@ -924,8 +1204,8 @@ export function registerItemCommands(program) {
     });
     // kspec item notes <ref>
     item
-        .command('notes <ref>')
-        .description('Show notes for a spec item')
+        .command("notes <ref>")
+        .description("Show notes for a spec item")
         .action(async (ref) => {
         try {
             const ctx = await initContext();
@@ -937,7 +1217,7 @@ export function registerItemCommands(program) {
                 error(errors.reference.itemNotFound(ref));
                 process.exit(EXIT_CODES.ERROR);
             }
-            const foundItem = items.find(i => i._ulid === result.ulid);
+            const foundItem = items.find((i) => i._ulid === result.ulid);
             if (!foundItem) {
                 error(errors.reference.itemNotFound(ref));
                 process.exit(EXIT_CODES.ERROR);
@@ -945,14 +1225,14 @@ export function registerItemCommands(program) {
             const notes = foundItem.notes || [];
             output(notes, () => {
                 if (notes.length === 0) {
-                    console.log('No notes');
+                    console.log("No notes");
                 }
                 else {
                     for (const note of notes) {
-                        const author = note.author || 'unknown';
+                        const author = note.author || "unknown";
                         console.log(`[${note.created_at}] ${author}:`);
                         console.log(note.content);
-                        console.log('');
+                        console.log("");
                     }
                 }
             });
@@ -964,14 +1244,14 @@ export function registerItemCommands(program) {
     });
     // Create subcommand group for acceptance criteria operations
     const acCmd = item
-        .command('ac')
-        .description('Manage acceptance criteria on spec items');
+        .command("ac")
+        .description("Manage acceptance criteria on spec items");
     // Helper: Generate next AC ID based on existing AC
     function generateNextAcId(existingAc) {
         if (!existingAc || existingAc.length === 0)
-            return 'ac-1';
+            return "ac-1";
         const numericIds = existingAc
-            .map(ac => ac.id.match(/^ac-(\d+)$/)?.[1])
+            .map((ac) => ac.id.match(/^ac-(\d+)$/)?.[1])
             .filter((id) => id !== null && id !== undefined)
             .map(Number);
         const maxId = numericIds.length > 0 ? Math.max(...numericIds) : 0;
@@ -988,7 +1268,7 @@ export function registerItemCommands(program) {
         }
         const foundItem = result.item;
         // Check if it's a task
-        if ('status' in foundItem && typeof foundItem.status === 'string') {
+        if ("status" in foundItem && typeof foundItem.status === "string") {
             error(errors.operation.tasksNoAcceptanceCriteria(ref));
             process.exit(EXIT_CODES.NOT_FOUND);
         }
@@ -996,8 +1276,8 @@ export function registerItemCommands(program) {
     }
     // kspec item ac list <ref>
     acCmd
-        .command('list <ref>')
-        .description('List acceptance criteria for a spec item')
+        .command("list <ref>")
+        .description("List acceptance criteria for a spec item")
         .action(async (ref) => {
         try {
             const { item, refIndex } = await resolveSpecItem(ref);
@@ -1006,7 +1286,7 @@ export function registerItemCommands(program) {
                 console.log(chalk.bold(`Acceptance Criteria for: ${item.title} (@${item.slugs[0] || refIndex.shortUlid(item._ulid)})`));
                 console.log();
                 if (ac.length === 0) {
-                    console.log(chalk.gray('No acceptance criteria'));
+                    console.log(chalk.gray("No acceptance criteria"));
                 }
                 else {
                     for (const criterion of ac) {
@@ -1026,13 +1306,12 @@ export function registerItemCommands(program) {
         }
     });
     // kspec item ac add <ref>
-    acCmd
-        .command('add <ref>')
-        .description('Add an acceptance criterion to a spec item')
-        .option('--id <id>', 'AC identifier (auto-generated if not provided)')
-        .requiredOption('--given <text>', 'The precondition (Given...)')
-        .requiredOption('--when <text>', 'The action/trigger (When...)')
-        .requiredOption('--then <text>', 'The expected outcome (Then...)')
+    markMutating(acCmd.command("add <ref>"))
+        .description("Add an acceptance criterion to a spec item")
+        .option("--id <id>", "AC identifier (auto-generated if not provided)")
+        .requiredOption("--given <text>", "The precondition (Given...)")
+        .requiredOption("--when <text>", "The action/trigger (When...)")
+        .requiredOption("--then <text>", "The expected outcome (Then...)")
         .action(async (ref, options) => {
         try {
             const { ctx, item, refIndex } = await resolveSpecItem(ref);
@@ -1040,7 +1319,7 @@ export function registerItemCommands(program) {
             // Determine ID
             const acId = options.id || generateNextAcId(existingAc);
             // Check for duplicate ID
-            if (existingAc.some(ac => ac.id === acId)) {
+            if (existingAc.some((ac) => ac.id === acId)) {
                 const itemRef = item.slugs[0] || refIndex.shortUlid(item._ulid);
                 error(errors.conflict.acAlreadyExists(acId, itemRef));
                 process.exit(EXIT_CODES.CONFLICT);
@@ -1056,8 +1335,10 @@ export function registerItemCommands(program) {
             const updatedAc = [...existingAc, newAc];
             await updateSpecItem(ctx, item, { acceptance_criteria: updatedAc });
             const itemSlug = item.slugs[0] || refIndex.shortUlid(item._ulid);
-            await commitIfShadow(ctx.shadow, 'item-ac-add', itemSlug);
-            success(`Added acceptance criterion: ${acId} to @${itemSlug}`, { ac: newAc });
+            await commitIfShadow(ctx.shadow, "item-ac-add", itemSlug);
+            success(`Added acceptance criterion: ${acId} to @${itemSlug}`, {
+                ac: newAc,
+            });
         }
         catch (err) {
             error(errors.failures.addAc, err);
@@ -1065,19 +1346,18 @@ export function registerItemCommands(program) {
         }
     });
     // kspec item ac set <ref> <ac-id>
-    acCmd
-        .command('set <ref> <acId>')
-        .description('Update an acceptance criterion')
-        .option('--id <newId>', 'Rename the AC ID')
-        .option('--given <text>', 'Update the precondition')
-        .option('--when <text>', 'Update the action/trigger')
-        .option('--then <text>', 'Update the expected outcome')
+    markMutating(acCmd.command("set <ref> <acId>"))
+        .description("Update an acceptance criterion")
+        .option("--id <newId>", "Rename the AC ID")
+        .option("--given <text>", "Update the precondition")
+        .option("--when <text>", "Update the action/trigger")
+        .option("--then <text>", "Update the expected outcome")
         .action(async (ref, acId, options) => {
         try {
             const { ctx, item, refIndex } = await resolveSpecItem(ref);
             const existingAc = item.acceptance_criteria || [];
             // Find the AC
-            const acIndex = existingAc.findIndex(ac => ac.id === acId);
+            const acIndex = existingAc.findIndex((ac) => ac.id === acId);
             if (acIndex === -1) {
                 const itemRef = item.slugs[0] || refIndex.shortUlid(item._ulid);
                 error(errors.reference.acNotFound(acId, itemRef));
@@ -1085,11 +1365,13 @@ export function registerItemCommands(program) {
             }
             // Check for no updates
             if (!options.id && !options.given && !options.when && !options.then) {
-                warn('No updates specified');
+                warn("No updates specified");
                 return;
             }
             // Check for duplicate ID if renaming
-            if (options.id && options.id !== acId && existingAc.some(ac => ac.id === options.id)) {
+            if (options.id &&
+                options.id !== acId &&
+                existingAc.some((ac) => ac.id === options.id)) {
                 error(errors.conflict.acIdAlreadyExists(options.id));
                 process.exit(EXIT_CODES.CONFLICT);
             }
@@ -1104,18 +1386,18 @@ export function registerItemCommands(program) {
                 ...(options.then && { then: options.then }),
             };
             if (options.id)
-                updatedFields.push('id');
+                updatedFields.push("id");
             if (options.given)
-                updatedFields.push('given');
+                updatedFields.push("given");
             if (options.when)
-                updatedFields.push('when');
+                updatedFields.push("when");
             if (options.then)
-                updatedFields.push('then');
+                updatedFields.push("then");
             // Update item
             await updateSpecItem(ctx, item, { acceptance_criteria: updatedAc });
             const itemSlug = item.slugs[0] || refIndex.shortUlid(item._ulid);
-            await commitIfShadow(ctx.shadow, 'item-ac-set', itemSlug);
-            success(`Updated acceptance criterion: ${acId} on @${itemSlug} (${updatedFields.join(', ')})`, { ac: updatedAc[acIndex] });
+            await commitIfShadow(ctx.shadow, "item-ac-set", itemSlug);
+            success(`Updated acceptance criterion: ${acId} on @${itemSlug} (${updatedFields.join(", ")})`, { ac: updatedAc[acIndex] });
         }
         catch (err) {
             error(errors.failures.updateAc, err);
@@ -1123,16 +1405,15 @@ export function registerItemCommands(program) {
         }
     });
     // kspec item ac remove <ref> <ac-id>
-    acCmd
-        .command('remove <ref> <acId>')
-        .description('Remove an acceptance criterion')
-        .option('--force', 'Skip confirmation')
+    markMutating(acCmd.command("remove <ref> <acId>"))
+        .description("Remove an acceptance criterion")
+        .option("--force", "Skip confirmation")
         .action(async (ref, acId, options) => {
         try {
             const { ctx, item, refIndex } = await resolveSpecItem(ref);
             const existingAc = item.acceptance_criteria || [];
             // Find the AC
-            const acIndex = existingAc.findIndex(ac => ac.id === acId);
+            const acIndex = existingAc.findIndex((ac) => ac.id === acId);
             if (acIndex === -1) {
                 const itemRef = item.slugs[0] || refIndex.shortUlid(item._ulid);
                 error(errors.reference.acNotFound(acId, itemRef));
@@ -1140,20 +1421,20 @@ export function registerItemCommands(program) {
             }
             // Confirmation required unless --force
             if (!options.force) {
-                // AC-5: JSON mode requires --force
+                // AC: @spec-item-delete-children ac-5 - JSON mode requires --force
                 if (isJsonMode()) {
-                    error('Confirmation required. Use --force with --json');
+                    error("Confirmation required. Use --force with --json");
                     process.exit(EXIT_CODES.ERROR);
                 }
-                // AC-6: Non-interactive environment requires --force
+                // AC: @spec-item-delete-children ac-6 - Non-interactive environment requires --force
                 // Allow KSPEC_TEST_TTY for testing interactive prompts
-                const isTTY = process.env.KSPEC_TEST_TTY === '1' || process.stdin.isTTY;
+                const isTTY = process.env.KSPEC_TEST_TTY === "1" || process.stdin.isTTY;
                 if (!isTTY) {
-                    error('Non-interactive environment. Use --force to proceed');
+                    error("Non-interactive environment. Use --force to proceed");
                     process.exit(EXIT_CODES.ERROR);
                 }
-                // AC-1: Prompt for confirmation
-                const readline = await import('readline');
+                // AC: @spec-item-delete-children ac-1 - Prompt for confirmation
+                const readline = await import("node:readline");
                 const rl = readline.createInterface({
                     input: process.stdin,
                     output: process.stdout,
@@ -1162,19 +1443,21 @@ export function registerItemCommands(program) {
                     rl.question(`Remove acceptance criterion ${acId}? [y/N] `, resolve);
                 });
                 rl.close();
-                // AC-3: User declines (n, N, or empty)
-                if (answer.toLowerCase() !== 'y') {
-                    error('Operation cancelled');
+                // AC: @spec-item-delete-children ac-3 - User declines (n, N, or empty)
+                if (answer.toLowerCase() !== "y") {
+                    error("Operation cancelled");
                     process.exit(EXIT_CODES.USAGE_ERROR);
                 }
             }
-            // AC-4: With --force, proceed immediately without prompt
-            // AC-2: User confirmed, proceed with removal
-            const updatedAc = existingAc.filter(ac => ac.id !== acId);
+            // AC: @spec-item-delete-children ac-4 - With --force, proceed immediately without prompt
+            // AC: @spec-item-delete-children ac-2 - User confirmed, proceed with removal
+            const updatedAc = existingAc.filter((ac) => ac.id !== acId);
             await updateSpecItem(ctx, item, { acceptance_criteria: updatedAc });
             const itemSlug = item.slugs[0] || refIndex.shortUlid(item._ulid);
-            await commitIfShadow(ctx.shadow, 'item-ac-remove', itemSlug);
-            success(`Removed acceptance criterion: ${acId} from @${itemSlug}`, { removed: acId });
+            await commitIfShadow(ctx.shadow, "item-ac-remove", itemSlug);
+            success(`Removed acceptance criterion: ${acId} from @${itemSlug}`, {
+                removed: acId,
+            });
         }
         catch (err) {
             error(errors.failures.removeAc, err);
@@ -1192,20 +1475,20 @@ async function readStdinFully() {
         return null;
     }
     return new Promise((resolve) => {
-        let data = '';
+        let data = "";
         const timeout = setTimeout(() => {
             process.stdin.removeAllListeners();
             resolve(data || null);
         }, 5000); // 5 second timeout for bulk input
-        process.stdin.setEncoding('utf8');
-        process.stdin.on('data', (chunk) => {
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
             data += chunk;
         });
-        process.stdin.on('end', () => {
+        process.stdin.on("end", () => {
             clearTimeout(timeout);
             resolve(data || null);
         });
-        process.stdin.on('error', () => {
+        process.stdin.on("error", () => {
             clearTimeout(timeout);
             resolve(null);
         });
@@ -1221,20 +1504,20 @@ async function readStdinIfAvailable() {
         return null;
     }
     return new Promise((resolve) => {
-        let data = '';
+        let data = "";
         const timeout = setTimeout(() => {
             process.stdin.removeAllListeners();
             resolve(data || null);
         }, 100); // 100ms timeout for quick check
-        process.stdin.setEncoding('utf8');
-        process.stdin.on('data', (chunk) => {
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
             data += chunk;
         });
-        process.stdin.on('end', () => {
+        process.stdin.on("end", () => {
             clearTimeout(timeout);
             resolve(data || null);
         });
-        process.stdin.on('error', () => {
+        process.stdin.on("error", () => {
             clearTimeout(timeout);
             resolve(null);
         });
@@ -1247,7 +1530,7 @@ async function readStdinIfAvailable() {
 function parseBulkInput(input) {
     const trimmed = input.trim();
     // Try JSON array first
-    if (trimmed.startsWith('[')) {
+    if (trimmed.startsWith("[")) {
         const parsed = JSON.parse(trimmed);
         if (!Array.isArray(parsed)) {
             throw new Error(errors.validation.expectedJsonArray);
@@ -1255,13 +1538,13 @@ function parseBulkInput(input) {
         return parsed.map((item, i) => validatePatchOperation(item, i));
     }
     // Parse as JSONL (one JSON object per line)
-    const lines = trimmed.split('\n').filter(line => line.trim());
+    const lines = trimmed.split("\n").filter((line) => line.trim());
     return lines.map((line, i) => {
         try {
             return validatePatchOperation(JSON.parse(line), i);
         }
         catch (err) {
-            throw new Error(errors.validation.jsonLineError(i + 1, err instanceof Error ? err.message : 'Invalid JSON'));
+            throw new Error(errors.validation.jsonLineError(i + 1, err instanceof Error ? err.message : "Invalid JSON"));
         }
     });
 }
@@ -1269,14 +1552,14 @@ function parseBulkInput(input) {
  * Validate a patch operation object
  */
 function validatePatchOperation(obj, index) {
-    if (!obj || typeof obj !== 'object') {
+    if (!obj || typeof obj !== "object") {
         throw new Error(errors.validation.patchMustBeObject(index));
     }
     const op = obj;
-    if (typeof op.ref !== 'string' || !op.ref) {
+    if (typeof op.ref !== "string" || !op.ref) {
         throw new Error(errors.validation.patchMustHaveRef(index));
     }
-    if (!op.data || typeof op.data !== 'object') {
+    if (!op.data || typeof op.data !== "object") {
         throw new Error(errors.validation.patchMustHaveData(index));
     }
     return { ref: op.ref, data: op.data };
@@ -1285,20 +1568,20 @@ function validatePatchOperation(obj, index) {
  * Format bulk patch result for human output
  */
 function formatBulkPatchResult(result, isDryRun = false) {
-    const prefix = isDryRun ? 'Would patch' : 'Patched';
+    const prefix = isDryRun ? "Would patch" : "Patched";
     for (const r of result.results) {
-        if (r.status === 'updated') {
-            console.log(chalk.green('OK'), `${prefix}: ${r.ref} (${r.ulid?.slice(0, 8)})`);
+        if (r.status === "updated") {
+            console.log(chalk.green("OK"), `${prefix}: ${r.ref} (${r.ulid?.slice(0, 8)})`);
         }
-        else if (r.status === 'error') {
-            console.log(chalk.red('ERR'), `${r.ref}: ${r.error}`);
+        else if (r.status === "error") {
+            console.log(chalk.red("ERR"), `${r.ref}: ${r.error}`);
         }
         else {
-            console.log(chalk.gray('SKIP'), r.ref);
+            console.log(chalk.gray("SKIP"), r.ref);
         }
     }
-    console.log('');
-    console.log(chalk.bold('Summary:'));
+    console.log("");
+    console.log(chalk.bold("Summary:"));
     console.log(`  Total: ${result.summary.total}`);
     console.log(chalk.green(`  Updated: ${result.summary.updated}`));
     if (result.summary.failed > 0) {