@kynetic-ai/spec 0.1.2 → 0.4.0

package/dist/merge/resolve.js

@@ -0,0 +1,189 @@
+/**
+ * Conflict resolution for semantic YAML merge.
+ *
+ * Handles interactive prompts for conflicts and formatting
+ * conflicts as YAML comments in non-interactive mode.
+ */
+import * as readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+/**
+ * AC: @yaml-merge-driver ac-4
+ * Prompt user interactively to resolve a scalar field conflict.
+ *
+ * @param conflict The conflict to resolve
+ * @param createInterface Optional readline factory for testing
+ * @returns The resolution choice and value
+ */
+export async function promptScalarConflict(conflict, createInterface) {
+    const factory = createInterface || readline.createInterface;
+    const rl = factory({ input, output });
+    try {
+        console.log(`\n${conflict.description}`);
+        console.log(`Path: ${conflict.path}`);
+        console.log(`  [1] Ours:   ${formatValue(conflict.oursValue)}`);
+        console.log(`  [2] Theirs: ${formatValue(conflict.theirsValue)}`);
+        console.log(`  [3] Skip (leave unresolved)`);
+        const answer = await rl.question("\nChoose [1/2/3]: ");
+        switch (answer.trim()) {
+            case "1":
+                return {
+                    conflict,
+                    choice: "ours",
+                    value: conflict.oursValue,
+                };
+            case "2":
+                return {
+                    conflict,
+                    choice: "theirs",
+                    value: conflict.theirsValue,
+                };
+            case "3":
+            default:
+                return {
+                    conflict,
+                    choice: "skip",
+                };
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * AC: @yaml-merge-driver ac-8
+ * Prompt user to choose between deletion and keeping modified version.
+ *
+ * @param conflict The delete-modify conflict to resolve
+ * @param createInterface Optional readline factory for testing
+ * @returns The resolution choice
+ */
+export async function promptDeleteModifyConflict(conflict, createInterface) {
+    const factory = createInterface || readline.createInterface;
+    const rl = factory({ input, output });
+    try {
+        console.log(`\n${conflict.description}`);
+        console.log(`Path: ${conflict.path}`);
+        // Determine which side deleted
+        const deletedInOurs = conflict.oursValue === undefined;
+        if (deletedInOurs) {
+            console.log(`  [1] Delete (ours deleted this)`);
+            console.log(`  [2] Keep modified version: ${formatValue(conflict.theirsValue)}`);
+        }
+        else {
+            console.log(`  [1] Keep modified version: ${formatValue(conflict.oursValue)}`);
+            console.log(`  [2] Delete (theirs deleted this)`);
+        }
+        console.log(`  [3] Skip (leave unresolved)`);
+        const answer = await rl.question("\nChoose [1/2/3]: ");
+        switch (answer.trim()) {
+            case "1":
+                return {
+                    conflict,
+                    choice: "ours",
+                    value: deletedInOurs ? undefined : conflict.oursValue,
+                };
+            case "2":
+                return {
+                    conflict,
+                    choice: "theirs",
+                    value: deletedInOurs ? conflict.theirsValue : undefined,
+                };
+            case "3":
+            default:
+                return {
+                    conflict,
+                    choice: "skip",
+                };
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Resolve multiple conflicts interactively.
+ *
+ * @param conflicts Array of conflicts to resolve
+ * @returns Array of resolutions
+ */
+export async function resolveConflictsInteractive(conflicts) {
+    const resolutions = [];
+    for (const conflict of conflicts) {
+        let resolution;
+        switch (conflict.type) {
+            case "scalar_field":
+                resolution = await promptScalarConflict(conflict);
+                break;
+            case "delete_modify":
+                resolution = await promptDeleteModifyConflict(conflict);
+                break;
+            case "nested_conflict":
+                // Nested conflicts should have been flattened to scalar conflicts
+                resolution = await promptScalarConflict(conflict);
+                break;
+        }
+        resolutions.push(resolution);
+    }
+    return resolutions;
+}
+/**
+ * AC: @yaml-merge-driver ac-10
+ * Format a conflict as a YAML comment for non-interactive mode.
+ *
+ * Example output:
+ * ```yaml
+ * # CONFLICT: Field "title" modified with different values in both branches
+ * # Path: tasks[0].title
+ * # Ours: "Fix authentication bug"
+ * # Theirs: "Fix auth issue"
+ * title: "Fix authentication bug"  # Using ours
+ * ```
+ *
+ * @param conflict The conflict to format
+ * @returns YAML comment lines
+ */
+export function formatConflictComment(conflict) {
+    const lines = [];
+    lines.push(`# CONFLICT: ${conflict.description}`);
+    lines.push(`# Path: ${conflict.path}`);
+    if (conflict.ulid) {
+        lines.push(`# ULID: ${conflict.ulid}`);
+    }
+    lines.push(`# Ours:   ${formatValue(conflict.oursValue)}`);
+    lines.push(`# Theirs: ${formatValue(conflict.theirsValue)}`);
+    lines.push(`# Resolution: Using ours (run merge interactively to resolve)`);
+    return lines;
+}
+/**
+ * Format a value for display in prompts or comments.
+ * Handles primitives, arrays, and objects concisely.
+ */
+function formatValue(value) {
+    if (value === undefined)
+        return "<deleted>";
+    if (value === null)
+        return "null";
+    if (typeof value === "string")
+        return `"${value}"`;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        if (value.length <= 3) {
+            return `[${value.map(formatValue).join(", ")}]`;
+        }
+        return `[${value.length} items]`;
+    }
+    if (typeof value === "object") {
+        const keys = Object.keys(value);
+        if (keys.length === 0)
+            return "{}";
+        if (keys.length === 1) {
+            return `{${keys[0]}}`;
+        }
+        return `{${keys.length} fields}`;
+    }
+    return String(value);
+}
+//# sourceMappingURL=resolve.js.map

package/dist/merge/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/merge/resolve.ts"],"names":[],"mappings":"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"}

package/dist/merge/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Types for semantic YAML merge driver.
+ *
+ * The merge driver parses kspec YAML files and merges them semantically,
+ * understanding the structure of tasks, items, and other entities.
+ */
+/**
+ * Result of a merge operation
+ */
+export interface MergeResult {
+    /** The merged YAML content */
+    content: string;
+    /** Whether conflicts were detected */
+    hasConflicts: boolean;
+    /** Conflict information (empty if no conflicts) */
+    conflicts: ConflictInfo[];
+    /** Whether parsing failed (triggers fallback) */
+    parseFailed: boolean;
+    /** Error message if parse failed */
+    parseError?: string;
+}
+/**
+ * Information about a conflict that requires resolution
+ */
+export interface ConflictInfo {
+    /** Type of conflict */
+    type: ConflictType;
+    /** Path to the conflicting field (e.g., "tasks[0].title") */
+    path: string;
+    /** ULID of the item with conflict (if applicable) */
+    ulid?: string;
+    /** Value from "ours" branch */
+    oursValue: unknown;
+    /** Value from "theirs" branch */
+    theirsValue: unknown;
+    /** Description of the conflict */
+    description: string;
+}
+/**
+ * Types of conflicts that can occur during merge
+ */
+export type ConflictType = "scalar_field" | "delete_modify" | "nested_conflict";
+/**
+ * Options for merge operations
+ */
+export interface MergeOptions {
+    /** Whether to run in non-interactive mode (no prompts) */
+    nonInteractive?: boolean;
+    /** Output file path for merged result */
+    outputPath: string;
+    /** Path to "base" version (common ancestor) */
+    basePath: string;
+    /** Path to "ours" version (current branch) */
+    oursPath: string;
+    /** Path to "theirs" version (incoming branch) */
+    theirsPath: string;
+}
+/**
+ * Parsed versions of a file for merging
+ */
+export interface ParsedVersions {
+    /** Common ancestor version */
+    base: unknown;
+    /** Current branch version */
+    ours: unknown;
+    /** Incoming branch version */
+    theirs: unknown;
+}
+/**
+ * Result of parsing all three versions
+ */
+export interface ParseResult {
+    /** Whether parsing succeeded */
+    success: boolean;
+    /** Parsed versions (undefined if parse failed) */
+    versions?: ParsedVersions;
+    /** Error message if parse failed */
+    error?: string;
+    /** Which file failed to parse (if applicable) */
+    failedFile?: "base" | "ours" | "theirs";
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/merge/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/merge/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,YAAY,EAAE,OAAO,CAAC;IACtB,mDAAmD;IACnD,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,iDAAiD;IACjD,WAAW,EAAE,OAAO,CAAC;IACrB,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uBAAuB;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,iCAAiC;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,cAAc,GACd,eAAe,GACf,iBAAiB,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,IAAI,EAAE,OAAO,CAAC;IACd,6BAA6B;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,8BAA8B;IAC9B,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;CACzC"}

package/dist/merge/types.js

@@ -0,0 +1,8 @@
+/**
+ * Types for semantic YAML merge driver.
+ *
+ * The merge driver parses kspec YAML files and merges them semantically,
+ * understanding the structure of tasks, items, and other entities.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/merge/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/merge/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/parser/agent-data-sections.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Auto-generated data sections for agent instructions.
+ *
+ * Library functions that generate markdown sections from kspec meta data:
+ * skills table, conventions summary, and workflows summary.
+ *
+ * AC: @agent-data-sections ac-1 - generateSkillsTable returns markdown table
+ * AC: @agent-data-sections ac-2 - generateConventionsSummary returns markdown section
+ * AC: @agent-data-sections ac-3 - generateWorkflowsSummary returns markdown section
+ */
+import type { LoadedConvention, LoadedSkill, LoadedWorkflow } from "./meta.js";
+/**
+ * Generate a markdown table for skills.
+ *
+ * AC: @agent-data-sections ac-1
+ * Given: skills in meta with varying names and descriptions
+ * When: generateSkillsTable is called
+ * Then: a markdown table is returned with columns for skill name, description, and invocation
+ *
+ * @param skills - Array of loaded skills from meta
+ * @returns Markdown table string with columns: name (as description), description, invocation
+ */
+export declare function generateSkillsTable(skills: LoadedSkill[]): string;
+/**
+ * Intro paragraph for the conventions section.
+ * Extracted as a constant for future configurability.
+ */
+export declare const CONVENTIONS_INTRO = "These are the project's agreed-upon conventions. Follow them in all contributions to maintain consistency.";
+/**
+ * Generate a markdown section summarizing conventions by domain.
+ *
+ * AC: @agent-data-sections ac-2
+ * Given: conventions in meta with rules arrays
+ * When: generateConventionsSummary is called
+ * Then: a markdown section is returned listing each domain with its rules
+ *
+ * @param conventions - Array of loaded conventions from meta
+ * @returns Markdown section string with domain headers, rules as list items, and examples
+ */
+export declare function generateConventionsSummary(conventions: LoadedConvention[]): string;
+/**
+ * Generate a markdown section summarizing workflows.
+ *
+ * AC: @agent-data-sections ac-3
+ * Given: workflows in meta with triggers and descriptions
+ * When: generateWorkflowsSummary is called
+ * Then: a markdown section is returned listing each workflow with its trigger
+ *
+ * @param workflows - Array of loaded workflows from meta
+ * @returns Markdown section string with workflow list including triggers
+ */
+export declare function generateWorkflowsSummary(workflows: LoadedWorkflow[]): string;
+//# sourceMappingURL=agent-data-sections.d.ts.map

package/dist/parser/agent-data-sections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-data-sections.d.ts","sourceRoot":"","sources":["../../src/parser/agent-data-sections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,CA4BjE;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,+GACgF,CAAC;AAE/G;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,gBAAgB,EAAE,GAC9B,MAAM,CAsCR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,MAAM,CAiB5E"}

package/dist/parser/agent-data-sections.js

@@ -0,0 +1,118 @@
+/**
+ * Auto-generated data sections for agent instructions.
+ *
+ * Library functions that generate markdown sections from kspec meta data:
+ * skills table, conventions summary, and workflows summary.
+ *
+ * AC: @agent-data-sections ac-1 - generateSkillsTable returns markdown table
+ * AC: @agent-data-sections ac-2 - generateConventionsSummary returns markdown section
+ * AC: @agent-data-sections ac-3 - generateWorkflowsSummary returns markdown section
+ */
+/**
+ * Generate a markdown table for skills.
+ *
+ * AC: @agent-data-sections ac-1
+ * Given: skills in meta with varying names and descriptions
+ * When: generateSkillsTable is called
+ * Then: a markdown table is returned with columns for skill name, description, and invocation
+ *
+ * @param skills - Array of loaded skills from meta
+ * @returns Markdown table string with columns: name (as description), description, invocation
+ */
+export function generateSkillsTable(skills) {
+    if (skills.length === 0) {
+        return "";
+    }
+    const lines = [
+        "## Finding Information",
+        "",
+        "Use skills and CLI help for detailed documentation:",
+        "",
+        "| Need | Where to look |",
+        "|------|---------------|",
+    ];
+    for (const skill of skills) {
+        const description = skill.description || skill.name;
+        // Core skills in plugin system are invoked as /kspec:<id>, project skills as /<id>
+        const invocation = skill.origin === "core" ? `kspec:${skill.id}` : skill.id;
+        lines.push(`| ${description} | \`/${invocation}\` skill |`);
+    }
+    lines.push("");
+    lines.push("Skills inject their full documentation when invoked — you don't need to memorize their contents.");
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Intro paragraph for the conventions section.
+ * Extracted as a constant for future configurability.
+ */
+export const CONVENTIONS_INTRO = "These are the project's agreed-upon conventions. Follow them in all contributions to maintain consistency.";
+/**
+ * Generate a markdown section summarizing conventions by domain.
+ *
+ * AC: @agent-data-sections ac-2
+ * Given: conventions in meta with rules arrays
+ * When: generateConventionsSummary is called
+ * Then: a markdown section is returned listing each domain with its rules
+ *
+ * @param conventions - Array of loaded conventions from meta
+ * @returns Markdown section string with domain headers, rules as list items, and examples
+ */
+export function generateConventionsSummary(conventions) {
+    if (conventions.length === 0) {
+        return "";
+    }
+    const lines = ["## Conventions", "", CONVENTIONS_INTRO, ""];
+    for (const convention of conventions) {
+        lines.push(`### ${convention.domain}`);
+        lines.push("");
+        for (const rule of convention.rules) {
+            lines.push(`- ${rule}`);
+        }
+        // Render examples when present
+        if (convention.examples && convention.examples.length > 0) {
+            lines.push("");
+            lines.push("**Examples:**");
+            for (const example of convention.examples) {
+                const combinedLength = example.good.length + example.bad.length;
+                if (combinedLength > 80) {
+                    // Long format: quoted, separate lines
+                    lines.push(`- Good: "${example.good}"`);
+                    lines.push(`- Bad: "${example.bad}"`);
+                }
+                else {
+                    // Short format: inline code with em-dash
+                    lines.push(`- Good: \`${example.good}\` — Bad: \`${example.bad}\``);
+                }
+            }
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Generate a markdown section summarizing workflows.
+ *
+ * AC: @agent-data-sections ac-3
+ * Given: workflows in meta with triggers and descriptions
+ * When: generateWorkflowsSummary is called
+ * Then: a markdown section is returned listing each workflow with its trigger
+ *
+ * @param workflows - Array of loaded workflows from meta
+ * @returns Markdown section string with workflow list including triggers
+ */
+export function generateWorkflowsSummary(workflows) {
+    if (workflows.length === 0) {
+        return "";
+    }
+    const lines = ["## Workflows", "", "Available workflows:", ""];
+    for (const workflow of workflows) {
+        const description = workflow.description || workflow.trigger;
+        lines.push(`- **${workflow.id}**: ${description}`);
+    }
+    lines.push("");
+    lines.push("Use `kspec workflow start @workflow-id` to start a workflow.");
+    lines.push("");
+    return lines.join("\n");
+}
+//# sourceMappingURL=agent-data-sections.js.map

package/dist/parser/agent-data-sections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-data-sections.js","sourceRoot":"","sources":["../../src/parser/agent-data-sections.ts"],"names":[],"mappings":"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"}

package/dist/parser/alignment.d.ts

@@ -4,9 +4,9 @@
  * Provides bidirectional mapping from spec items to implementing tasks,
  * and detects alignment issues like orphaned specs or stale implementation status.
  */
-import type { LoadedSpecItem, LoadedTask, KspecContext } from './yaml.js';
-import type { ReferenceIndex } from './refs.js';
-import type { ImplementationStatus } from '../schema/index.js';
+import type { ImplementationStatus } from "../schema/index.js";
+import type { ReferenceIndex } from "./refs.js";
+import type { KspecContext, LoadedSpecItem, LoadedTask } from "./yaml.js";
 /**
  * Summary of a spec item's implementation status based on linked tasks
  */
@@ -31,7 +31,7 @@ export interface LinkedTaskSummary {
  * Alignment warning
  */
 export interface AlignmentWarning {
-    type: 'orphaned_spec' | 'status_mismatch' | 'stale_implementation';
+    type: "orphaned_spec" | "status_mismatch" | "stale_implementation";
     specUlid?: string;
     specTitle?: string;
     taskUlid?: string;

package/dist/parser/alignment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alignment.d.ts","sourceRoot":"","sources":["../../src/parser/alignment.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAM/D;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,oBAAoB,CAAC;IACpC,cAAc,EAAE,oBAAoB,CAAC;IACrC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,sBAAsB,CAAC;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;GAGG;AACH,qBAAa,cAAc;IACzB,+CAA+C;IAC/C,OAAO,CAAC,WAAW,CAA+B;IAElD,0CAA0C;IAC1C,OAAO,CAAC,UAAU,CAA6B;IAE/C,6BAA6B;IAC7B,OAAO,CAAC,SAAS,CAAqC;IAEtD,wBAAwB;IACxB,OAAO,CAAC,KAAK,CAAiC;IAE9C;;OAEG;gBACS,KAAK,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE;IAkBxD;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAa1C;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE;IAO/C;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,cAAc,GAAG,SAAS;IAWtF;;OAEG;IACH,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB;IA4B/D;;OAEG;IACH,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,yBAAyB,GAAG,SAAS;IA4BjF;;OAEG;IACH,qBAAqB,IAAI,gBAAgB,EAAE;IA4C3C;;OAEG;IACH,6BAA6B,IAAI,yBAAyB,EAAE;IAW5D;;OAEG;IACH,QAAQ,IAAI;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;KACvB;CAyBF;AAMD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,oBAAoB,CAAC;IACrC,SAAS,EAAE,oBAAoB,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAChD,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,UAAU,EAAE,EACtB,QAAQ,EAAE,cAAc,EAAE,EAC1B,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA6C5B"}
+{"version":3,"file":"alignment.d.ts","sourceRoot":"","sources":["../../src/parser/alignment.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAO1E;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,oBAAoB,CAAC;IACpC,cAAc,EAAE,oBAAoB,CAAC;IACrC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,sBAAsB,CAAC;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;GAGG;AACH,qBAAa,cAAc;IACzB,+CAA+C;IAC/C,OAAO,CAAC,WAAW,CAA+B;IAElD,0CAA0C;IAC1C,OAAO,CAAC,UAAU,CAA6B;IAE/C,6BAA6B;IAC7B,OAAO,CAAC,SAAS,CAAqC;IAEtD,wBAAwB;IACxB,OAAO,CAAC,KAAK,CAAiC;IAE9C;;OAEG;gBACS,KAAK,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE;IAkBxD;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAa1C;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE;IAO/C;;OAEG;IACH,cAAc,CACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,cAAc,GACvB,cAAc,GAAG,SAAS;IAW7B;;OAEG;IACH,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB;IA4B/D;;OAEG;IACH,wBAAwB,CACtB,QAAQ,EAAE,MAAM,GACf,yBAAyB,GAAG,SAAS;IA4BxC;;OAEG;IACH,qBAAqB,IAAI,gBAAgB,EAAE;IAmD3C;;OAEG;IACH,6BAA6B,IAAI,yBAAyB,EAAE;IAW5D;;OAEG;IACH,QAAQ,IAAI;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;KACvB;CAyBF;AAMD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,oBAAoB,CAAC;IACrC,SAAS,EAAE,oBAAoB,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAChD,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,UAAU,EAAE,EACtB,QAAQ,EAAE,cAAc,EAAE,EAC1B,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA6C5B"}

package/dist/parser/alignment.js

@@ -4,7 +4,7 @@
  * Provides bidirectional mapping from spec items to implementing tasks,
  * and detects alignment issues like orphaned specs or stale implementation status.
  */
-import { updateSpecItem } from './yaml.js';
+import { updateSpecItem } from "./yaml.js";
 // ============================================================
 // ALIGNMENT INDEX
 // ============================================================
@@ -61,7 +61,7 @@ export class AlignmentIndex {
     getTasksForSpec(specUlid) {
         const taskUlids = this.specToTasks.get(specUlid) || [];
         return taskUlids
-            .map(ulid => this.tasks.get(ulid))
+            .map((ulid) => this.tasks.get(ulid))
             .filter((t) => t !== undefined);
     }
     /**
@@ -83,25 +83,25 @@ export class AlignmentIndex {
     calculateExpectedStatus(specUlid) {
         const taskUlids = this.specToTasks.get(specUlid) || [];
         if (taskUlids.length === 0) {
-            return 'not_started';
+            return "not_started";
         }
         const tasks = taskUlids
-            .map(ulid => this.tasks.get(ulid))
+            .map((ulid) => this.tasks.get(ulid))
             .filter((t) => t !== undefined);
         if (tasks.length === 0) {
-            return 'not_started';
+            return "not_started";
         }
         // Check task statuses
-        const hasInProgress = tasks.some(t => t.status === 'in_progress');
-        const allCompleted = tasks.every(t => t.status === 'completed');
-        const someCompleted = tasks.some(t => t.status === 'completed');
+        const hasInProgress = tasks.some((t) => t.status === "in_progress");
+        const allCompleted = tasks.every((t) => t.status === "completed");
+        const someCompleted = tasks.some((t) => t.status === "completed");
         if (allCompleted) {
-            return 'implemented';
+            return "implemented";
         }
         if (hasInProgress || someCompleted) {
-            return 'in_progress';
+            return "in_progress";
         }
-        return 'not_started';
+        return "not_started";
     }
     /**
      * Get implementation summary for a spec item
@@ -112,15 +112,15 @@ export class AlignmentIndex {
             return undefined;
         const taskUlids = this.specToTasks.get(specUlid) || [];
         const linkedTasks = taskUlids
-            .map(ulid => this.tasks.get(ulid))
+            .map((ulid) => this.tasks.get(ulid))
             .filter((t) => t !== undefined)
-            .map(t => ({
+            .map((t) => ({
             taskUlid: t._ulid,
             taskTitle: t.title,
             taskStatus: t.status,
             hasNotes: t.notes.length > 0,
         }));
-        const currentStatus = spec.status?.implementation || 'not_started';
+        const currentStatus = spec.status?.implementation || "not_started";
         const expectedStatus = this.calculateExpectedStatus(specUlid);
         return {
             specUlid,
@@ -139,12 +139,17 @@ export class AlignmentIndex {
         // Check each spec item
         for (const [specUlid, spec] of this.specItems) {
             const taskUlids = this.specToTasks.get(specUlid) || [];
-            const currentStatus = spec.status?.implementation || 'not_started';
+            const currentStatus = spec.status?.implementation || "not_started";
             const expectedStatus = this.calculateExpectedStatus(specUlid);
             // Orphaned spec (no tasks)
-            if (taskUlids.length === 0 && currentStatus === 'not_started') {
+            // AC: @trait-retrospective ac-1
+            // Skip retrospective specs from orphaned warnings
+            const isRetrospective = spec.traits?.includes("@trait-retrospective");
+            if (taskUlids.length === 0 &&
+                currentStatus === "not_started" &&
+                !isRetrospective) {
                 warnings.push({
-                    type: 'orphaned_spec',
+                    type: "orphaned_spec",
                     specUlid,
                     specTitle: spec.title,
                     message: `Spec item "${spec.title}" has no implementing tasks`,
@@ -153,7 +158,7 @@ export class AlignmentIndex {
             // Status mismatch
             if (currentStatus !== expectedStatus) {
                 warnings.push({
-                    type: 'status_mismatch',
+                    type: "status_mismatch",
                     specUlid,
                     specTitle: spec.title,
                     message: `Spec "${spec.title}" status is "${currentStatus}" but should be "${expectedStatus}" based on task progress`,
@@ -162,7 +167,7 @@ export class AlignmentIndex {
         }
         // Check completed tasks with stale spec status
         for (const [taskUlid, task] of this.tasks) {
-            if (task.status === 'completed' && task.spec_ref) {
+            if (task.status === "completed" && task.spec_ref) {
                 const specRef = this.taskToSpec.get(taskUlid);
                 if (specRef) {
                     // Note: We already checked this via spec iteration above
@@ -230,7 +235,7 @@ export async function syncSpecImplementationStatus(ctx, task, allTasks, allItems
         return null;
     }
     // Find the spec item
-    const specItem = allItems.find(item => item._ulid === result.ulid);
+    const specItem = allItems.find((item) => item._ulid === result.ulid);
     if (!specItem) {
         return null;
     }
@@ -238,7 +243,7 @@ export async function syncSpecImplementationStatus(ctx, task, allTasks, allItems
     const alignmentIndex = new AlignmentIndex(allTasks, allItems);
     alignmentIndex.buildLinks(refIndex);
     const expectedStatus = alignmentIndex.calculateExpectedStatus(specItem._ulid);
-    const currentStatus = specItem.status?.implementation || 'not_started';
+    const currentStatus = specItem.status?.implementation || "not_started";
     // No change needed
     if (currentStatus === expectedStatus) {
         return null;
@@ -246,7 +251,7 @@ export async function syncSpecImplementationStatus(ctx, task, allTasks, allItems
     // Update the spec item
     await updateSpecItem(ctx, specItem, {
         status: {
-            maturity: specItem.status?.maturity || 'draft',
+            maturity: specItem.status?.maturity || "draft",
             implementation: expectedStatus,
         },
     });