@kynetic-ai/spec 0.11.0 → 0.12.0

package/dist/parser/review-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-validation.d.ts","sourceRoot":"","sources":["../../src/parser/review-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAG3D;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,qBAAqB,EAAE,CAAC;CACjC;AAsDD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,GACd,sBAAsB,CAoBxB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,GACd,sBAAsB,CAoBxB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,qBAAqB,EAAE,CAAC,CA2DlC;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAsBpE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,6BAA6B,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,qBAAqB,EAAE,CAAA;CAAE,CAOzH;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,6BAA6B,EAAE,iBAAiB,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,qBAAqB,EAAE,CAAA;CAAE,CAM9H"}

package/dist/parser/review-validation.js

@@ -0,0 +1,207 @@
+/**
+ * Validation module for review records.
+ *
+ * Provides schema validation for review records, threads, checks, verdicts,
+ * events, and subject bindings. Used during parsing, persistence, and
+ * command mutation to ensure review data integrity.
+ *
+ * AC: @review-record-validation ac-1, ac-2
+ */
+import * as path from "node:path";
+import { ReviewRecordSchema, ReviewRecordsFileSchema, ReviewRecordInputSchema, } from "../schema/review-records.js";
+import { readYamlFile } from "./yaml.js";
+/**
+ * Provide actionable guidance for common review validation failures.
+ *
+ * AC: @review-record-validation ac-2
+ */
+function formatActionableMessage(fieldPath, message) {
+    // Subject type discrimination errors
+    if (fieldPath.includes("subject") && message.includes("discriminator")) {
+        return `${message}. Subject type must be one of: code, plan, task, spec, external`;
+    }
+    // Subject version discrimination errors
+    if (fieldPath.includes("applies_to_version") && message.includes("discriminator")) {
+        return `${message}. Version type must be one of: code_compare, entity_version`;
+    }
+    // Anchor type discrimination errors
+    if (fieldPath.includes("anchor") && message.includes("discriminator")) {
+        return `${message}. Anchor type must be one of: code, structured`;
+    }
+    // Missing required title
+    if (fieldPath.endsWith("title") && message.includes("too_small")) {
+        return "Title is required and must be non-empty";
+    }
+    // Invalid URL
+    if (message.includes("Invalid url")) {
+        return `${message}. Provide a valid URL (e.g., https://example.com)`;
+    }
+    // Invalid ULID
+    if (fieldPath.endsWith("_ulid") && (message.includes("String must contain") || message.includes("Invalid"))) {
+        return `${message}. ULIDs must be exactly 26 uppercase alphanumeric characters (Crockford base32)`;
+    }
+    // Invalid enum value
+    if (message.includes("Invalid enum value")) {
+        return message;
+    }
+    // Invalid datetime
+    if (message.includes("Invalid datetime")) {
+        return `${message}. Use ISO 8601 format (e.g., 2026-03-14T00:00:00.000Z)`;
+    }
+    return message;
+}
+/**
+ * Validate a single review record against the full ReviewRecordSchema.
+ * Use this when validating persisted or loaded review records.
+ *
+ * AC: @review-record-validation ac-1
+ */
+export function validateReviewRecord(data, source) {
+    const errors = [];
+    const file = source ?? "review-record";
+    const result = ReviewRecordSchema.safeParse(data);
+    if (!result.success) {
+        for (const issue of result.error.issues) {
+            errors.push({
+                file,
+                path: issue.path.join("."),
+                message: formatActionableMessage(issue.path.join("."), issue.message),
+                details: issue,
+            });
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Validate review record input (for creating new reviews).
+ * Uses ReviewRecordInputSchema which has relaxed requirements.
+ *
+ * AC: @review-record-validation ac-1, ac-2
+ */
+export function validateReviewRecordInput(data, source) {
+    const errors = [];
+    const file = source ?? "review-record-input";
+    const result = ReviewRecordInputSchema.safeParse(data);
+    if (!result.success) {
+        for (const issue of result.error.issues) {
+            errors.push({
+                file,
+                path: issue.path.join("."),
+                message: formatActionableMessage(issue.path.join("."), issue.message),
+                details: issue,
+            });
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Validate a reviews YAML file (project.reviews.yaml).
+ * Validates the file-level schema and each individual review record.
+ *
+ * AC: @review-record-validation ac-1, ac-2
+ */
+export async function validateReviewsFile(filePath) {
+    const errors = [];
+    try {
+        const raw = await readYamlFile(filePath);
+        if (!raw || typeof raw !== "object") {
+            errors.push({
+                file: filePath,
+                message: "Invalid reviews file format: expected an object with { kynetic_reviews, reviews }",
+            });
+            return errors;
+        }
+        // Validate the full file schema
+        const fileResult = ReviewRecordsFileSchema.safeParse(raw);
+        if (!fileResult.success) {
+            // Try to give per-review errors for better diagnostics
+            const rawObj = raw;
+            if (Array.isArray(rawObj.reviews)) {
+                for (let i = 0; i < rawObj.reviews.length; i++) {
+                    const reviewResult = ReviewRecordSchema.safeParse(rawObj.reviews[i]);
+                    if (!reviewResult.success) {
+                        for (const issue of reviewResult.error.issues) {
+                            const fieldPath = `reviews[${i}].${issue.path.join(".")}`;
+                            errors.push({
+                                file: filePath,
+                                path: fieldPath,
+                                message: formatActionableMessage(fieldPath, issue.message),
+                                details: issue,
+                            });
+                        }
+                    }
+                }
+            }
+            // If no per-review errors were found, report file-level errors
+            if (errors.length === 0) {
+                for (const issue of fileResult.error.issues) {
+                    errors.push({
+                        file: filePath,
+                        path: issue.path.join("."),
+                        message: formatActionableMessage(issue.path.join("."), issue.message),
+                        details: issue,
+                    });
+                }
+            }
+        }
+    }
+    catch (err) {
+        errors.push({
+            file: filePath,
+            message: `Failed to parse reviews YAML: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+    return errors;
+}
+/**
+ * Find review files in a directory (files matching *.reviews.yaml).
+ */
+export async function findReviewFiles(dir) {
+    const files = [];
+    try {
+        const { readdir } = await import("node:fs/promises");
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                const subFiles = await findReviewFiles(fullPath);
+                files.push(...subFiles);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".reviews.yaml")) {
+                files.push(fullPath);
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or not readable
+    }
+    return files;
+}
+/**
+ * Convenience: parse and validate a review record, returning the typed
+ * result on success or errors on failure.
+ *
+ * AC: @review-record-validation ac-1, ac-2
+ */
+export function parseReviewRecord(data, source) {
+    const result = validateReviewRecord(data, source);
+    if (!result.valid) {
+        return { ok: false, errors: result.errors };
+    }
+    // Safe to parse — validation already passed
+    return { ok: true, data: ReviewRecordSchema.parse(data) };
+}
+/**
+ * Convenience: parse and validate review record input, returning the typed
+ * result on success or errors on failure.
+ *
+ * AC: @review-record-validation ac-1, ac-2
+ */
+export function parseReviewRecordInput(data, source) {
+    const result = validateReviewRecordInput(data, source);
+    if (!result.valid) {
+        return { ok: false, errors: result.errors };
+    }
+    return { ok: true, data: ReviewRecordInputSchema.parse(data) };
+}
+//# sourceMappingURL=review-validation.js.map

package/dist/parser/review-validation.js.map

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

package/dist/parser/reviews.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Review record loading and operations.
+ *
+ * Review records are first-party top-level entities stored in
+ * project.reviews.yaml with stable ULID-backed identity.
+ *
+ * AC: @review-record-storage-and-identity ac-1 - Dedicated first-party review storage
+ * AC: @review-record-storage-and-identity ac-3 - Single dedicated file per project
+ */
+import { type ReviewRecord, type ReviewRecordInput } from "../schema/index.js";
+import type { KspecContext } from "./yaml.js";
+/**
+ * Loaded review record with runtime metadata.
+ * AC: @review-record-storage-and-identity ac-2 - ULID-backed identity
+ */
+export interface LoadedReviewRecord extends ReviewRecord {
+    _sourceFile?: string;
+}
+/**
+ * Get the reviews file path.
+ * AC: @review-record-storage-and-identity ac-3 - single dedicated file per project
+ */
+export declare function getReviewsFilePath(ctx: KspecContext): string;
+/**
+ * Load all review records from the project.
+ * AC: @review-record-storage-and-identity ac-1 - dedicated first-party review storage
+ * AC: @review-record-storage-and-identity ac-3 - single dedicated file per project
+ */
+export declare function loadReviewRecords(ctx: KspecContext): Promise<LoadedReviewRecord[]>;
+/**
+ * Find a review record by reference (ULID, short ULID, or slug).
+ * AC: @review-record-storage-and-identity ac-2 - addressable by @review ref
+ */
+export declare function findReviewByRef(reviews: LoadedReviewRecord[], ref: string): LoadedReviewRecord | undefined;
+/**
+ * Create a new review record from input.
+ * AC: @review-record-storage-and-identity ac-2 - ULID-backed identity
+ */
+export declare function createReviewRecord(input: ReviewRecordInput): ReviewRecord;
+/**
+ * Save a single review record (create or update).
+ * AC: @review-record-storage-and-identity ac-1 - dedicated first-party review storage
+ * AC: @review-record-storage-and-identity ac-3 - single dedicated file per project
+ * Uses file lock to prevent TOCTOU race on concurrent writes.
+ */
+export declare function saveReviewRecord(ctx: KspecContext, review: LoadedReviewRecord): Promise<void>;
+/**
+ * Atomically mutate a review record using the latest on-disk state.
+ *
+ * The callback receives the current review value while holding the file lock,
+ * so concurrent writers do not clobber unrelated fields.
+ */
+export declare function mutateReviewAtomically(ctx: KspecContext, review: LoadedReviewRecord, mutate: (latestReview: LoadedReviewRecord) => ReviewRecord | LoadedReviewRecord | Promise<ReviewRecord | LoadedReviewRecord>): Promise<LoadedReviewRecord>;
+/**
+ * Delete a review record by ULID.
+ */
+export declare function deleteReviewRecord(ctx: KspecContext, reviewUlid: string): Promise<boolean>;
+//# sourceMappingURL=reviews.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reviews.d.ts","sourceRoot":"","sources":["../../src/parser/reviews.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EAIvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAE5D;AAmDD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,YAAY,GAChB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAa/B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,kBAAkB,EAAE,EAC7B,GAAG,EAAE,MAAM,GACV,kBAAkB,GAAG,SAAS,CAYhC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,CAqBzE;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,YAAY,EACjB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,IAAI,CAAC,CAmCf;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,YAAY,EACjB,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,CACN,YAAY,EAAE,kBAAkB,KAC7B,YAAY,GAAG,kBAAkB,GAAG,OAAO,CAAC,YAAY,GAAG,kBAAkB,CAAC,GAClF,OAAO,CAAC,kBAAkB,CAAC,CAiD7B;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,YAAY,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAyBlB"}

package/dist/parser/reviews.js

@@ -0,0 +1,230 @@
+/**
+ * Review record loading and operations.
+ *
+ * Review records are first-party top-level entities stored in
+ * project.reviews.yaml with stable ULID-backed identity.
+ *
+ * AC: @review-record-storage-and-identity ac-1 - Dedicated first-party review storage
+ * AC: @review-record-storage-and-identity ac-3 - Single dedicated file per project
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { ulid } from "ulid";
+import { withFileLock } from "./file-lock.js";
+import { ReviewRecordSchema, ReviewRecordsFileSchema, } from "../schema/index.js";
+import { readYamlFile, writeYamlFilePreserveFormat } from "./yaml.js";
+/**
+ * Get the reviews file path.
+ * AC: @review-record-storage-and-identity ac-3 - single dedicated file per project
+ */
+export function getReviewsFilePath(ctx) {
+    return path.join(ctx.specDir, "project.reviews.yaml");
+}
+/**
+ * Parse review records from raw YAML payload.
+ *
+ * Supports the canonical { kynetic_reviews, reviews } shape and a fallback
+ * { reviews } shape for older files without version metadata.
+ */
+function parseReviewsFromRaw(raw) {
+    const parsed = ReviewRecordsFileSchema.safeParse(raw);
+    if (parsed.success) {
+        return parsed.data.reviews;
+    }
+    if (raw && typeof raw === "object" && "reviews" in raw) {
+        const fallbackReviews = raw.reviews;
+        if (Array.isArray(fallbackReviews)) {
+            const reviews = [];
+            for (const review of fallbackReviews) {
+                const reviewResult = ReviewRecordSchema.safeParse(review);
+                if (reviewResult.success) {
+                    reviews.push(reviewResult.data);
+                }
+            }
+            return reviews;
+        }
+    }
+    return [];
+}
+/**
+ * Load review records from an explicit file path.
+ */
+async function loadReviewsFromFile(reviewsPath) {
+    const raw = await readYamlFile(reviewsPath);
+    return parseReviewsFromRaw(raw);
+}
+/**
+ * Strip runtime metadata before serialization.
+ */
+function stripReviewMetadata(review) {
+    const { _sourceFile, ...cleanReview } = review;
+    return cleanReview;
+}
+/**
+ * Load all review records from the project.
+ * AC: @review-record-storage-and-identity ac-1 - dedicated first-party review storage
+ * AC: @review-record-storage-and-identity ac-3 - single dedicated file per project
+ */
+export async function loadReviewRecords(ctx) {
+    const reviewsPath = getReviewsFilePath(ctx);
+    try {
+        const reviews = await loadReviewsFromFile(reviewsPath);
+        return reviews.map((review) => ({
+            ...review,
+            _sourceFile: reviewsPath,
+        }));
+    }
+    catch {
+        // File doesn't exist or parse error
+        return [];
+    }
+}
+/**
+ * Find a review record by reference (ULID, short ULID, or slug).
+ * AC: @review-record-storage-and-identity ac-2 - addressable by @review ref
+ */
+export function findReviewByRef(reviews, ref) {
+    const cleanRef = ref.startsWith("@") ? ref.slice(1) : ref;
+    return reviews.find((r) => 
+    // Match full ULID
+    r._ulid === cleanRef ||
+        // Match short ULID (prefix)
+        r._ulid.toLowerCase().startsWith(cleanRef.toLowerCase()) ||
+        // Match any slug
+        r.slugs.includes(cleanRef));
+}
+/**
+ * Create a new review record from input.
+ * AC: @review-record-storage-and-identity ac-2 - ULID-backed identity
+ */
+export function createReviewRecord(input) {
+    const now = new Date().toISOString();
+    return {
+        _ulid: input._ulid ?? ulid(),
+        slugs: input.slugs ?? [],
+        title: input.title,
+        lifecycle_state: input.lifecycle_state ?? "draft",
+        subject: input.subject,
+        author: input.author,
+        related_refs: input.related_refs ?? [],
+        threads: input.threads ?? [],
+        checks: input.checks ?? [],
+        verdicts: input.verdicts ?? [],
+        events: input.events ?? [],
+        notes: input.notes ?? [],
+        external_links: input.external_links ?? [],
+        examined_commit: input.examined_commit ?? null,
+        created_at: input.created_at ?? now,
+        updated_at: input.updated_at ?? null,
+    };
+}
+/**
+ * Save a single review record (create or update).
+ * AC: @review-record-storage-and-identity ac-1 - dedicated first-party review storage
+ * AC: @review-record-storage-and-identity ac-3 - single dedicated file per project
+ * Uses file lock to prevent TOCTOU race on concurrent writes.
+ */
+export async function saveReviewRecord(ctx, review) {
+    const reviewsPath = getReviewsFilePath(ctx);
+    // Lock the file to prevent concurrent read-modify-write races
+    await withFileLock(reviewsPath, async () => {
+        // Ensure directory exists
+        const dir = path.dirname(reviewsPath);
+        await fs.mkdir(dir, { recursive: true });
+        // Load existing reviews (inside lock to prevent TOCTOU)
+        let reviews = [];
+        try {
+            reviews = await loadReviewsFromFile(reviewsPath);
+        }
+        catch {
+            // File doesn't exist yet, start fresh
+        }
+        const cleanReview = stripReviewMetadata(review);
+        // Update or add
+        const existingIndex = reviews.findIndex((r) => r._ulid === review._ulid);
+        if (existingIndex >= 0) {
+            reviews[existingIndex] = cleanReview;
+        }
+        else {
+            reviews.push(cleanReview);
+        }
+        // Save back to file
+        const reviewsFile = {
+            kynetic_reviews: "1.0",
+            reviews,
+        };
+        await writeYamlFilePreserveFormat(reviewsPath, reviewsFile);
+    });
+}
+/**
+ * Atomically mutate a review record using the latest on-disk state.
+ *
+ * The callback receives the current review value while holding the file lock,
+ * so concurrent writers do not clobber unrelated fields.
+ */
+export async function mutateReviewAtomically(ctx, review, mutate) {
+    const reviewsPath = review._sourceFile || getReviewsFilePath(ctx);
+    let updatedReview;
+    await withFileLock(reviewsPath, async () => {
+        // Ensure directory exists
+        const dir = path.dirname(reviewsPath);
+        await fs.mkdir(dir, { recursive: true });
+        let reviews = [];
+        try {
+            reviews = await loadReviewsFromFile(reviewsPath);
+        }
+        catch {
+            throw new Error(`Reviews file not found: ${reviewsPath}`);
+        }
+        const reviewIndex = reviews.findIndex((candidate) => candidate._ulid === review._ulid);
+        if (reviewIndex === -1) {
+            throw new Error(`Review not found in file: ${review._ulid}`);
+        }
+        const latestReview = {
+            ...reviews[reviewIndex],
+            _sourceFile: reviewsPath,
+        };
+        const mutatedReview = await mutate(latestReview);
+        const cleanMutatedReview = stripReviewMetadata(mutatedReview);
+        reviews[reviewIndex] = cleanMutatedReview;
+        const reviewsFile = {
+            kynetic_reviews: "1.0",
+            reviews,
+        };
+        await writeYamlFilePreserveFormat(reviewsPath, reviewsFile);
+        updatedReview = {
+            ...cleanMutatedReview,
+            _sourceFile: reviewsPath,
+        };
+    });
+    if (!updatedReview) {
+        throw new Error(`Failed to mutate review atomically: ${review._ulid}`);
+    }
+    return updatedReview;
+}
+/**
+ * Delete a review record by ULID.
+ */
+export async function deleteReviewRecord(ctx, reviewUlid) {
+    const reviewsPath = getReviewsFilePath(ctx);
+    return withFileLock(reviewsPath, async () => {
+        try {
+            const reviews = await loadReviewsFromFile(reviewsPath);
+            const index = reviews.findIndex((r) => r._ulid === reviewUlid);
+            if (index < 0) {
+                return false;
+            }
+            reviews.splice(index, 1);
+            const reviewsFile = {
+                kynetic_reviews: "1.0",
+                reviews,
+            };
+            await writeYamlFilePreserveFormat(reviewsPath, reviewsFile);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+//# sourceMappingURL=reviews.js.map

package/dist/parser/reviews.js.map

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

package/dist/parser/session-branch.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Session branch worktree management.
+ *
+ * When sessions.storage is "branch", sessions are stored in a git worktree
+ * on a named orphan branch (default: "kspec-sessions") at .kspec-sessions/.
+ * This provides git-tracked session persistence independent of kspec-meta.
+ *
+ * AC: @session-branch-worktree — all ACs
+ */
+import { type ShadowSyncResult } from "./shadow.js";
+/** Default session branch name */
+export declare const SESSION_BRANCH_NAME = "kspec-sessions";
+/** Configuration for session branch mode */
+export interface SessionBranchConfig {
+    /** Whether session branch mode is enabled */
+    enabled: boolean;
+    /** Path to .kspec-sessions/ worktree directory */
+    worktreeDir: string;
+    /** Session branch name (default: kspec-sessions) */
+    branchName: string;
+    /** Project root */
+    projectRoot: string;
+}
+/** Status of the session branch worktree */
+export interface SessionBranchStatus {
+    exists: boolean;
+    healthy: boolean;
+    branchExists: boolean;
+    worktreeExists: boolean;
+    worktreeLinked: boolean;
+    error?: string;
+}
+/** Result from session branch initialization */
+export interface SessionBranchInitResult {
+    success: boolean;
+    branchCreated: boolean;
+    worktreeCreated: boolean;
+    alreadyExists: boolean;
+    error?: string;
+}
+/**
+ * Get the status of the session branch worktree.
+ *
+ * AC: @session-branch-worktree ac-status
+ */
+export declare function getSessionBranchStatus(projectRoot: string, branchName?: string): Promise<SessionBranchStatus>;
+/**
+ * Initialize session branch worktree.
+ * Creates an orphan branch and worktree at .kspec-sessions/.
+ *
+ * AC: @session-branch-worktree ac-init
+ */
+export declare function initializeSessionBranch(projectRoot: string, branchName?: string): Promise<SessionBranchInitResult>;
+/**
+ * Repair a broken session branch worktree.
+ *
+ * AC: @session-branch-worktree ac-repair
+ */
+export declare function repairSessionBranch(projectRoot: string, branchName?: string): Promise<SessionBranchInitResult>;
+/**
+ * Auto-commit changes to the session branch.
+ * Called at session lifecycle boundaries (create, close, stale cleanup, compact).
+ *
+ * AC: @session-branch-worktree ac-commit-boundaries
+ */
+export declare function sessionBranchAutoCommit(worktreeDir: string, message: string): Promise<boolean>;
+/**
+ * Commit session changes if session branch mode is enabled.
+ * Respects batch mode (suppresses commits during atomic batch execution).
+ *
+ * AC: @session-branch-worktree ac-commit-boundaries
+ */
+export declare function commitIfSessionBranch(config: SessionBranchConfig | null, operation: string, sessionId?: string): Promise<boolean>;
+/**
+ * Pull remote changes for the session branch.
+ * Uses in-flight dedup to prevent concurrent pulls.
+ *
+ * AC: @session-branch-worktree ac-sync
+ */
+export declare function sessionBranchPull(worktreeDir: string, branchName?: string): Promise<ShadowSyncResult>;
+/**
+ * Resolve session branch config from manifest.
+ * Returns null if sessions.storage is not "branch".
+ */
+export declare function resolveSessionBranchConfig(projectRoot: string, manifest: {
+    sessions?: {
+        storage?: string;
+        branch?: string;
+    };
+} | null): SessionBranchConfig | null;
+//# sourceMappingURL=session-branch.d.ts.map

package/dist/parser/session-branch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-branch.d.ts","sourceRoot":"","sources":["../../src/parser/session-branch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EAQL,KAAK,gBAAgB,EAEtB,MAAM,aAAa,CAAC;AAOrB,kCAAkC;AAClC,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAIpD,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gDAAgD;AAChD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAgDD;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,EACnB,UAAU,GAAE,MAA4B,GACvC,OAAO,CAAC,mBAAmB,CAAC,CAgD9B;AAID;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,UAAU,GAAE,MAA4B,GACvC,OAAO,CAAC,uBAAuB,CAAC,CA6KlC;AAID;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,UAAU,GAAE,MAA4B,GACvC,OAAO,CAAC,uBAAuB,CAAC,CAwElC;AAID;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CAoElB;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,mBAAmB,GAAG,IAAI,EAClC,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAelB;AAWD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,UAAU,GAAE,MAA4B,GACvC,OAAO,CAAC,gBAAgB,CAAC,CAW3B;AA+GD;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE;IAAE,QAAQ,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAAG,IAAI,GACpE,mBAAmB,GAAG,IAAI,CAa5B"}