@kynetic-ai/spec 0.10.0 → 0.12.0

package/dist/parser/yaml.js

@@ -9,8 +9,10 @@ import { InboxFileSchema, InboxItemSchema, ManifestSchema, SpecItemSchema, TaskS
 import { errors } from "../strings/index.js";
 import { ItemIndex } from "./items.js";
 import { ReferenceIndex } from "./refs.js";
-import { detectRunningFromShadowWorktree, detectShadow, ShadowError, } from "./shadow.js";
+import { loadReviewRecords } from "./reviews.js";
+import { createShadowError, detectRunningFromShadowWorktree, detectShadow, getShadowStatus, hasRemoteTracking, resolveProjectRoots, shadowNeedsSync, shadowPull, ShadowError, } from "./shadow.js";
 import { loadProjectConfig, } from "./config.js";
+import { consumeSyncMode } from "../cli/sync-mode.js";
 import { TraitIndex } from "./traits.js";
 /**
  * Log a debug message (only when KSPEC_DEBUG=1)
@@ -54,11 +56,98 @@ export function parseYaml(content) {
  * causes lines containing only spaces to grow. We post-process the output to filter
  * these whitespace-only lines. See: https://github.com/eemeli/yaml - stringifyString.ts
  */
+/**
+ * Canonical key priority tiers for YAML serialization.
+ * Keys are sorted by tier first, then alphabetically within each tier.
+ * _ulid is always first (tier 0). Keys not listed default to tier 50.
+ */
+const KEY_PRIORITY = {
+    // Tier 0: ULID — always first for record boundary detection
+    _ulid: 0,
+    // Tier 1: Identity fields
+    slugs: 1,
+    title: 2,
+    type: 3,
+    // Tier 2: Content / description
+    description: 10,
+    text: 10,
+    content: 10,
+    // Tier 3: Spec relationships
+    spec_ref: 15,
+    derivation: 16,
+    meta_ref: 17,
+    plan_ref: 18,
+    origin: 19,
+    // Tier 4: Status / state
+    status: 20,
+    maturity: 20,
+    blocked_by: 21,
+    closed_reason: 22,
+    disposition: 23,
+    // Tier 5: Relationships
+    depends_on: 25,
+    context: 26,
+    implements: 27,
+    relates_to: 28,
+    tests: 29,
+    traits: 30,
+    supersedes: 31,
+    acceptance_criteria: 32,
+    // Tier 6: Work metadata
+    priority: 35,
+    complexity: 36,
+    tags: 37,
+    assignee: 38,
+    // Tier 7: VCS / review
+    vcs_refs: 40,
+    review_url: 41,
+    review_ref: 42,
+    submission_linkage: 43,
+    session_id: 44,
+    // Tier 8: Timestamps
+    created: 60,
+    created_at: 60,
+    created_by: 61,
+    started_at: 62,
+    submitted_at: 63,
+    completed_at: 64,
+    updated_at: 65,
+    acted_at: 66,
+    deprecated_in: 67,
+    superseded_by: 68,
+    verified_at: 69,
+    verified_by: 70,
+    // Tier 9: Audit / append-only
+    notes: 80,
+    todos: 81,
+    // Tier 10: Automation / config
+    automation: 90,
+    traceability: 91,
+};
+/**
+ * Compare two YAML map entries for canonical field ordering.
+ * _ulid is always first. Known keys are ordered by priority tier,
+ * with alphabetical tiebreaking within the same tier.
+ * Unknown keys sort after tier 50 (alphabetically among themselves).
+ */
+export function canonicalKeyComparator(a, b) {
+    const aKey = String(a.key);
+    const bKey = String(b.key);
+    const aPriority = KEY_PRIORITY[aKey] ?? 50;
+    const bPriority = KEY_PRIORITY[bKey] ?? 50;
+    if (aPriority !== bPriority)
+        return aPriority - bPriority;
+    return aKey.localeCompare(bKey);
+}
 export function toYaml(obj) {
-    let yamlString = YAML.stringify(obj, {
+    // JSON round-trip breaks shared object references so the yaml library
+    // won't generate anchors/aliases that crash when sortMapEntries reorders keys.
+    // structuredClone preserves shared refs, so JSON.parse(JSON.stringify()) is needed.
+    const cloned = JSON.parse(JSON.stringify(obj));
+    let yamlString = YAML.stringify(cloned, {
         indent: 2,
         lineWidth: 100,
-        sortMapEntries: false,
+        sortMapEntries: canonicalKeyComparator,
     });
     // Post-process to fix yaml library blank line accumulation bug.
     // Filter out lines that contain only spaces/tabs (not truly empty lines).
@@ -108,7 +197,7 @@ export async function writeYamlFile(filePath, data) {
         buffer.write(filePath, content);
         return;
     }
-    await fs.writeFile(filePath, content, "utf-8");
+    await writeFileAtomic(filePath, content);
 }
 /**
  * Write object to YAML file while preserving formatting and comments.
@@ -125,7 +214,14 @@ export async function writeYamlFilePreserveFormat(filePath, data) {
         buffer.write(filePath, content);
         return;
     }
-    await fs.writeFile(filePath, content, "utf-8");
+    await writeFileAtomic(filePath, content);
+}
+async function writeFileAtomic(filePath, content) {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    await fs.writeFile(tmpPath, content, "utf-8");
+    await fs.rename(tmpPath, filePath);
 }
 /**
  * Find task files in a directory
@@ -204,9 +300,10 @@ export async function findManifest(startDir) {
  */
 export async function initContext(startDir) {
     const cwd = startDir || process.cwd();
+    const projectRoots = resolveProjectRoots(cwd);
     // AC: @project-config ac-2, ac-6, ac-7 — load config before shadow detection
     // Config is loaded from git root, not cwd or KSPEC_SPEC_DIR temp dir
-    const configResult = await loadProjectConfig(cwd);
+    const configResult = await loadProjectConfig(cwd, projectRoots?.mainRoot);
     // AC: @project-config ac-3 — emit warning to stderr if config had issues
     if (configResult.warning) {
         console.error(`Warning: ${configResult.warning}`);
@@ -227,9 +324,12 @@ export async function initContext(startDir) {
                 // Manifest exists but may be invalid
             }
         }
+        const rootDir = path.dirname(specDir);
         return {
-            rootDir: path.dirname(specDir),
+            rootDir,
+            projectRoot: rootDir,
             specDir,
+            sessionsDir: path.join(rootDir, ".kspec-sessions"),
             manifestPath,
             manifest,
             shadow: null, // No shadow in overridden context
@@ -247,10 +347,54 @@ export async function initContext(startDir) {
     const shadow = await detectShadow(cwd, {
         branchName: config.shadow.branch,
         directory: config.shadow.directory,
-    });
+    }, projectRoots?.mainRoot);
     if (shadow?.enabled) {
         // Shadow mode: use .kspec/ for everything
         const specDir = shadow.worktreeDir;
+        // AC: @shadow-lazy-read-sync ac-no-sync-env — KSPEC_NO_SYNC disables all sync
+        // AC: @shadow-lazy-read-sync ac-syncmode-consume-once — consume-once prevents double-pull
+        // AC: @shadow-lazy-read-sync ac-drift-check — drift check replaces unconditional pull
+        if (!process.env.KSPEC_NO_SYNC) {
+            const syncMode = consumeSyncMode();
+            // AC: @config-shadow ac-3 ac-7 — pass configured shadow options so sync
+            // uses the right branch name and remote instead of hardcoded defaults
+            const shadowOpts = {
+                branchName: config.shadow.branch,
+                directory: config.shadow.directory,
+                remote: config.shadow.remote?.value,
+                remoteType: config.shadow.remote?.type,
+            };
+            // AC: @shadow-write-sync ac-write-skips-read-check — skip pre-read sync for mutating commands
+            if (syncMode !== "skip") {
+                try {
+                    const tracked = await hasRemoteTracking(specDir, shadowOpts);
+                    if (tracked) {
+                        let shouldPull = false;
+                        if (syncMode === "always") {
+                            // AC: @shadow-lazy-read-sync ac-session-start-always-pulls
+                            shouldPull = true;
+                        }
+                        else {
+                            // AC: @shadow-lazy-read-sync ac-drift-check — lightweight drift check
+                            // AC: @shadow-lazy-read-sync ac-threshold-from-config
+                            const remoteName = config.shadow.remote?.value ?? "origin";
+                            const thresholdMs = config.shadow.sync_interval * 1000;
+                            shouldPull = await shadowNeedsSync(specDir, remoteName, thresholdMs);
+                        }
+                        if (shouldPull) {
+                            const syncResult = await shadowPull(specDir, shadowOpts);
+                            if (syncResult.hadConflict) {
+                                console.error("Warning: Shadow sync conflict detected. Run `kspec shadow resolve` to fix.");
+                                console.error("Continuing with local state...");
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // Pre-read sync is best-effort — don't fail the command
+                }
+            }
+        }
         const manifestPath = await findManifestInDir(specDir);
         let manifest = null;
         if (manifestPath) {
@@ -263,19 +407,33 @@ export async function initContext(startDir) {
             }
         }
         return {
-            rootDir: shadow.projectRoot,
+            rootDir: projectRoots?.worktreeRoot ?? shadow.projectRoot,
+            projectRoot: shadow.projectRoot,
             specDir,
+            sessionsDir: path.join(shadow.projectRoot, ".kspec-sessions"),
             manifestPath,
             manifest,
             shadow,
             config,
         };
     }
+    // Fail closed when a repo already has shadow state but the configured worktree
+    // is missing or disconnected, rather than silently degrading into repo-root mode.
+    if (projectRoots?.mainRoot) {
+        const shadowStatus = await getShadowStatus(projectRoots.mainRoot, {
+            branchName: config.shadow.branch,
+            directory: config.shadow.directory,
+        });
+        if (shadowStatus.branchExists && !shadowStatus.healthy) {
+            throw createShadowError(shadowStatus);
+        }
+    }
     // Traditional mode: find manifest in spec/ or current directory
     const manifestPath = await findManifest(cwd);
     let manifest = null;
-    let rootDir = cwd;
-    let specDir = cwd;
+    let rootDir = projectRoots?.worktreeRoot ?? cwd;
+    const projectRoot = projectRoots?.mainRoot ?? rootDir;
+    let specDir = rootDir;
     if (manifestPath) {
         const manifestDir = path.dirname(manifestPath);
         // Handle spec/ subdirectory
@@ -295,7 +453,16 @@ export async function initContext(startDir) {
             // Manifest exists but may be invalid
         }
     }
-    return { rootDir, specDir, manifestPath, manifest, shadow: null, config };
+    return {
+        rootDir,
+        projectRoot,
+        specDir,
+        sessionsDir: path.join(projectRoot, ".kspec-sessions"),
+        manifestPath,
+        manifest,
+        shadow: null,
+        config,
+    };
 }
 /**
  * Check if a filename is a potential manifest file.
@@ -321,7 +488,7 @@ function isManifestCandidate(filename) {
  *
  * AC: @manifest-discovery ac-1, ac-2, ac-3, ac-4, ac-5
  */
-async function findManifestInDir(dir) {
+export async function findManifestInDir(dir) {
     // AC: @manifest-discovery ac-1, ac-2 - explicit names have priority
     const priorityCandidates = ["kynetic.yaml", "kynetic.spec.yaml"];
     for (const candidate of priorityCandidates) {
@@ -513,9 +680,96 @@ function stripRuntimeMetadata(task) {
     const { _sourceFile, ...cleanTask } = task;
     return cleanTask;
 }
+/**
+ * Extract the raw task array and format info from a YAML file.
+ * Does NOT run schema validation — preserves original data for round-trip stability.
+ */
+async function extractRawTaskArray(filePath) {
+    let existingRaw = null;
+    let useTasksWrapper = false;
+    try {
+        existingRaw = await readYamlFile(filePath);
+        if (existingRaw &&
+            typeof existingRaw === "object" &&
+            "tasks" in existingRaw) {
+            useTasksWrapper = true;
+        }
+    }
+    catch {
+        // File doesn't exist
+        return { rawTasks: [], useTasksWrapper: false };
+    }
+    if (!existingRaw) {
+        return { rawTasks: [], useTasksWrapper: false };
+    }
+    if (Array.isArray(existingRaw)) {
+        return { rawTasks: existingRaw, useTasksWrapper: false };
+    }
+    if (useTasksWrapper) {
+        const wrapper = existingRaw;
+        const tasks = wrapper.tasks;
+        return {
+            rawTasks: Array.isArray(tasks) ? tasks : [],
+            useTasksWrapper: true,
+            wrapperObj: wrapper,
+        };
+    }
+    return { rawTasks: [], useTasksWrapper: false };
+}
+/**
+ * Write raw task array back to file, preserving the wrapper format.
+ */
+async function writeRawTaskArray(filePath, rawTasks, useTasksWrapper, wrapperObj) {
+    if (useTasksWrapper) {
+        // Preserve any extra top-level fields (e.g. kynetic_tasks version)
+        const output = wrapperObj ? { ...wrapperObj, tasks: rawTasks } : { tasks: rawTasks };
+        await writeYamlFilePreserveFormat(filePath, output);
+    }
+    else {
+        await writeYamlFilePreserveFormat(filePath, rawTasks);
+    }
+}
+/**
+ * Find task index in a raw array by ULID match.
+ */
+function findRawTaskIndex(rawTasks, ulid) {
+    return rawTasks.findIndex((t) => t && typeof t === "object" && t._ulid === ulid);
+}
+/**
+ * Merge a schema-normalized task onto the original raw task data.
+ * Only adds fields that were in the original raw data or that contain
+ * non-default values. This prevents Zod defaults from polluting YAML
+ * output with fields that weren't originally present.
+ *
+ * Fields present in rawTask are always updated with the new value.
+ * Fields NOT in rawTask are only added if they carry meaningful data
+ * (i.e. non-empty arrays, non-null values, etc.).
+ */
+function mergeTaskPreservingRawShape(rawTask, normalizedTask) {
+    const result = {};
+    for (const [key, value] of Object.entries(normalizedTask)) {
+        if (key in rawTask) {
+            // Field existed in raw — always include (even if value changed)
+            result[key] = value;
+        }
+        else {
+            // Field was added by schema normalization — only include if non-trivial
+            const isEmptyArray = Array.isArray(value) && value.length === 0;
+            const isNull = value === null || value === undefined;
+            if (!isEmptyArray && !isNull) {
+                result[key] = value;
+            }
+        }
+    }
+    return result;
+}
 /**
  * Save a task to its source file (or default location for new tasks).
  * Preserves file format (tasks: [...] wrapper vs plain array).
+ *
+ * Non-target tasks are preserved as raw data (no schema parsing) to ensure
+ * round-trip stability — fields not present in the original YAML won't be
+ * added by Zod defaults.
  */
 export async function saveTask(ctx, task) {
     // Determine target file: use _sourceFile if present, otherwise default
@@ -525,70 +779,21 @@ export async function saveTask(ctx, task) {
         // Ensure directory exists
         const dir = path.dirname(taskFilePath);
         await fs.mkdir(dir, { recursive: true });
-        // Load existing tasks from the target file
-        let existingRaw = null;
-        let useTasksWrapper = false;
-        try {
-            existingRaw = await readYamlFile(taskFilePath);
-            // Detect if file uses { tasks: [...] } format
-            if (existingRaw &&
-                typeof existingRaw === "object" &&
-                "tasks" in existingRaw) {
-                useTasksWrapper = true;
-            }
-        }
-        catch {
-            // File doesn't exist, start fresh
-        }
-        // Parse existing tasks from file
-        let fileTasks = [];
-        if (existingRaw) {
-            if (Array.isArray(existingRaw)) {
-                for (const t of existingRaw) {
-                    const result = TaskSchema.safeParse(t);
-                    if (result.success) {
-                        fileTasks.push(result.data);
-                    }
-                }
-            }
-            else if (useTasksWrapper) {
-                // Try TasksFileSchema first (has kynetic_tasks version)
-                const parsed = TasksFileSchema.safeParse(existingRaw);
-                if (parsed.success) {
-                    fileTasks = parsed.data.tasks;
-                }
-                else {
-                    // Fall back to raw tasks array (common format without version field)
-                    const rawTasks = existingRaw.tasks;
-                    if (Array.isArray(rawTasks)) {
-                        for (const t of rawTasks) {
-                            const result = TaskSchema.safeParse(t);
-                            if (result.success) {
-                                fileTasks.push(result.data);
-                            }
-                        }
-                    }
-                }
-            }
-        }
+        // Load raw task data without schema normalization
+        const { rawTasks, useTasksWrapper, wrapperObj } = await extractRawTaskArray(taskFilePath);
         // Strip runtime metadata before saving
         const cleanTask = stripRuntimeMetadata(task);
-        // Update existing or add new
-        const existingIndex = fileTasks.findIndex((t) => t._ulid === task._ulid);
+        // Update existing or add new — replace only the target task
+        const existingIndex = findRawTaskIndex(rawTasks, task._ulid);
         if (existingIndex >= 0) {
-            fileTasks[existingIndex] = cleanTask;
-        }
-        else {
-            fileTasks.push(cleanTask);
-        }
-        // Save in the same format as original (or tasks: wrapper for new files)
-        // Use format-preserving write to maintain formatting and comments
-        if (useTasksWrapper) {
-            await writeYamlFilePreserveFormat(taskFilePath, { tasks: fileTasks });
+            // Merge onto raw data to avoid adding Zod defaults for absent fields
+            const rawTarget = rawTasks[existingIndex];
+            rawTasks[existingIndex] = mergeTaskPreservingRawShape(rawTarget, cleanTask);
         }
         else {
-            await writeYamlFilePreserveFormat(taskFilePath, fileTasks);
+            rawTasks.push(cleanTask);
         }
+        await writeRawTaskArray(taskFilePath, rawTasks, useTasksWrapper, wrapperObj);
     });
 }
 /**
@@ -596,6 +801,9 @@ export async function saveTask(ctx, task) {
  *
  * The callback receives the current task value while holding the task file lock,
  * so concurrent writers cannot clobber unrelated fields (for example status vs notes).
+ *
+ * Non-target tasks are preserved as raw data (no schema parsing) to ensure
+ * round-trip stability.
  */
 export async function mutateTaskAtomically(ctx, task, mutate) {
     const taskFilePath = task._sourceFile || getDefaultTaskFilePath(ctx);
@@ -604,35 +812,24 @@ export async function mutateTaskAtomically(ctx, task, mutate) {
         // Ensure directory exists (important for default path in new repos)
         const dir = path.dirname(taskFilePath);
         await fs.mkdir(dir, { recursive: true });
-        // Preserve existing file format (tasks wrapper vs plain array)
-        let existingRaw = null;
-        let useTasksWrapper = false;
-        try {
-            existingRaw = await readYamlFile(taskFilePath);
-            if (existingRaw &&
-                typeof existingRaw === "object" &&
-                "tasks" in existingRaw) {
-                useTasksWrapper = true;
-            }
-        }
-        catch {
-            throw new Error(`Task file not found: ${taskFilePath}`);
-        }
-        const fileTasks = await loadTasksFromFile(taskFilePath);
-        const taskIndex = fileTasks.findIndex((t) => t._ulid === task._ulid);
+        // Load raw task data without schema normalization for non-target tasks
+        const { rawTasks, useTasksWrapper, wrapperObj } = await extractRawTaskArray(taskFilePath);
+        const taskIndex = findRawTaskIndex(rawTasks, task._ulid);
         if (taskIndex === -1) {
             throw new Error(`Task not found in file: ${task._ulid}`);
         }
-        const latestTask = fileTasks[taskIndex];
+        // Schema-parse only the target task for the mutation callback
+        const rawTarget = rawTasks[taskIndex];
+        const parsed = TaskSchema.safeParse(rawTarget);
+        if (!parsed.success) {
+            throw new Error(`Invalid task data for ${task._ulid}: ${parsed.error.message}`);
+        }
+        const latestTask = { ...parsed.data, _sourceFile: taskFilePath };
         const mutatedTask = await mutate(latestTask);
         const cleanMutatedTask = stripRuntimeMetadata(mutatedTask);
-        const serializedTasks = fileTasks.map((fileTask, index) => index === taskIndex ? cleanMutatedTask : stripRuntimeMetadata(fileTask));
-        if (useTasksWrapper) {
-            await writeYamlFilePreserveFormat(taskFilePath, { tasks: serializedTasks });
-        }
-        else {
-            await writeYamlFilePreserveFormat(taskFilePath, serializedTasks);
-        }
+        // Merge onto raw data to avoid adding Zod defaults for absent fields
+        rawTasks[taskIndex] = mergeTaskPreservingRawShape(rawTarget, cleanMutatedTask);
+        await writeRawTaskArray(taskFilePath, rawTasks, useTasksWrapper, wrapperObj);
         updatedTask = {
             ...cleanMutatedTask,
             _sourceFile: taskFilePath,
@@ -654,62 +851,18 @@ export async function deleteTask(_ctx, task) {
     const taskFilePath = task._sourceFile;
     // Lock the file to prevent concurrent read-modify-write races
     await withFileLock(taskFilePath, async () => {
-        // Load existing file
-        let existingRaw = null;
-        let useTasksWrapper = false;
-        try {
-            existingRaw = await readYamlFile(taskFilePath);
-            if (existingRaw &&
-                typeof existingRaw === "object" &&
-                "tasks" in existingRaw) {
-                useTasksWrapper = true;
-            }
-        }
-        catch {
+        // Load raw task data without schema normalization for round-trip stability
+        const { rawTasks, useTasksWrapper, wrapperObj } = await extractRawTaskArray(taskFilePath);
+        if (rawTasks.length === 0) {
             throw new Error(`Task file not found: ${taskFilePath}`);
         }
-        // Parse existing tasks
-        let fileTasks = [];
-        if (existingRaw) {
-            if (Array.isArray(existingRaw)) {
-                for (const t of existingRaw) {
-                    const result = TaskSchema.safeParse(t);
-                    if (result.success) {
-                        fileTasks.push(result.data);
-                    }
-                }
-            }
-            else if (useTasksWrapper) {
-                const parsed = TasksFileSchema.safeParse(existingRaw);
-                if (parsed.success) {
-                    fileTasks = parsed.data.tasks;
-                }
-                else {
-                    const rawTasks = existingRaw.tasks;
-                    if (Array.isArray(rawTasks)) {
-                        for (const t of rawTasks) {
-                            const result = TaskSchema.safeParse(t);
-                            if (result.success) {
-                                fileTasks.push(result.data);
-                            }
-                        }
-                    }
-                }
-            }
-        }
-        // Remove the task
-        const originalCount = fileTasks.length;
-        fileTasks = fileTasks.filter((t) => t._ulid !== task._ulid);
-        if (fileTasks.length === originalCount) {
+        // Remove the task by ULID match on raw data
+        const taskIndex = findRawTaskIndex(rawTasks, task._ulid);
+        if (taskIndex === -1) {
             throw new Error(`Task not found in file: ${task._ulid}`);
         }
-        // Save the modified file with format preservation
-        if (useTasksWrapper) {
-            await writeYamlFilePreserveFormat(taskFilePath, { tasks: fileTasks });
-        }
-        else {
-            await writeYamlFilePreserveFormat(taskFilePath, fileTasks);
-        }
+        rawTasks.splice(taskIndex, 1);
+        await writeRawTaskArray(taskFilePath, rawTasks, useTasksWrapper, wrapperObj);
     });
 }
 /**
@@ -1126,7 +1279,8 @@ export function findAnyItemByRef(tasks, items, ref) {
 export async function buildReferenceIndex(ctx) {
     const tasks = await loadAllTasks(ctx);
     const items = await loadAllItems(ctx);
-    const index = new ReferenceIndex(tasks, items);
+    const reviews = await loadReviewRecords(ctx);
+    const index = new ReferenceIndex(tasks, items, [], [], reviews);
     return { index, tasks, items };
 }
 /**
@@ -1138,7 +1292,8 @@ export async function buildReferenceIndex(ctx) {
 export async function buildIndexes(ctx, plans = []) {
     const tasks = await loadAllTasks(ctx);
     const items = await loadAllItems(ctx);
-    const refIndex = new ReferenceIndex(tasks, items, [], plans);
+    const reviews = await loadReviewRecords(ctx);
+    const refIndex = new ReferenceIndex(tasks, items, [], plans, reviews);
     const itemIndex = new ItemIndex(tasks, items);
     const traitIndex = new TraitIndex(items, refIndex);
     return { refIndex, itemIndex, traitIndex, tasks, items };
@@ -1318,6 +1473,31 @@ export async function addChildItem(_ctx, parent, child, childField) {
         return { item: cleanChild, path: childPath };
     });
 }
+/**
+ * Add a trait item to the project-level traits array in kynetic.yaml.
+ */
+export async function addProjectLevelTraitItem(ctx, item) {
+    if (!ctx.manifestPath) {
+        throw new Error("Could not find kynetic.yaml");
+    }
+    return withFileLock(ctx.manifestPath, async () => {
+        const manifest = await readYamlFile(ctx.manifestPath);
+        if (!manifest) {
+            throw new Error("Could not load kynetic.yaml");
+        }
+        if (!Array.isArray(manifest.traits)) {
+            manifest.traits = [];
+        }
+        const cleanItem = stripSpecItemMetadata(item);
+        manifest.traits.push(cleanItem);
+        await writeYamlFilePreserveFormat(ctx.manifestPath, manifest);
+        const traitIndex = manifest.traits.length - 1;
+        return {
+            item: cleanItem,
+            path: `traits[${traitIndex}]`,
+        };
+    });
+}
 /**
  * Update a spec item in place within its source file.
  * Works with nested structures using the _path field.