openplanr 1.2.7 → 1.3.0

package/dist/services/git-service.js

@@ -0,0 +1,137 @@
+/**
+ * Git integration for `planr revise`.
+ *
+ * Two responsibilities:
+ *
+ * 1. **Clean-tree gate:** revise refuses to run with a dirty
+ *    working tree by default. Users can override with `--allow-dirty`, but
+ *    post-flight rollback depends on a clean pre-run state, so the gate is
+ *    the load-bearing safety net.
+ *
+ * 2. **Capture + rollback anchor:** before bulk writes,
+ *    revise captures HEAD and the set of touched paths so a post-flight
+ *    graph-integrity failure can restore via `git checkout`.
+ *
+ * All git operations use `execFile` (not shell), matching the pattern in
+ * github-service.ts. If git is not available or the project is not a git
+ * repo, clean-tree checks fail closed (revise refuses to run) unless
+ * --allow-dirty is passed, because without git there is no safety net.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const GIT_MAX_BUFFER = 10 * 1024 * 1024;
+/**
+ * Inspect the working tree. Never throws — always returns a typed status so
+ * callers can render errors consistently.
+ */
+export async function inspectGitTree(projectDir) {
+    let head;
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], {
+            cwd: projectDir,
+            maxBuffer: GIT_MAX_BUFFER,
+        });
+        head = stdout.trim();
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (/not a git repository|fatal:.*repository/i.test(message)) {
+            return { kind: 'not-a-repo', reason: message };
+        }
+        if (/ENOENT|git: not found|command not found/i.test(message)) {
+            return { kind: 'git-missing', reason: message };
+        }
+        // Empty repo (no commits yet) also reaches here; treat it as not-a-repo
+        // for clean-tree gating purposes — there is no HEAD to roll back to.
+        if (/unknown revision|does not have any commits/i.test(message)) {
+            return { kind: 'not-a-repo', reason: 'git repository has no commits yet' };
+        }
+        return { kind: 'not-a-repo', reason: message };
+    }
+    const { stdout: porcelain } = await execFileAsync('git', ['status', '--porcelain'], {
+        cwd: projectDir,
+        maxBuffer: GIT_MAX_BUFFER,
+    });
+    if (porcelain.trim().length === 0) {
+        return { kind: 'clean', head };
+    }
+    const changedPaths = porcelain
+        .split('\n')
+        .filter((line) => line.length > 0)
+        .map((line) => line.slice(3).trim());
+    return { kind: 'dirty', head, changedPaths };
+}
+/**
+ * The clean-tree gate: clean → pass; dirty → pass only when --allow-dirty;
+ * missing git / not a repo → fail closed unless --allow-dirty was passed
+ * (because without git there is no post-flight rollback safety net).
+ */
+export async function checkCleanTree(projectDir, options) {
+    const status = await inspectGitTree(projectDir);
+    switch (status.kind) {
+        case 'clean':
+            return {
+                ok: true,
+                status,
+                message: `Working tree is clean at ${status.head.slice(0, 12)}.`,
+            };
+        case 'dirty':
+            if (options.allowDirty) {
+                return {
+                    ok: true,
+                    status,
+                    message: `Working tree has ${status.changedPaths.length} uncommitted change(s); running with --allow-dirty. Post-flight rollback cannot restore these changes.`,
+                };
+            }
+            return {
+                ok: false,
+                status,
+                message: `Working tree has ${status.changedPaths.length} uncommitted change(s). Commit or stash them, or re-run with --allow-dirty (post-flight rollback cannot restore uncommitted work).`,
+            };
+        case 'not-a-repo':
+            if (options.allowDirty) {
+                return {
+                    ok: true,
+                    status,
+                    message: `Not a git repository (${status.reason.trim()}); running with --allow-dirty. Post-flight rollback is disabled.`,
+                };
+            }
+            return {
+                ok: false,
+                status,
+                message: `Not a git repository (${status.reason.trim()}). Revise requires git for its post-flight rollback safety net. Initialize git, or re-run with --allow-dirty to opt out of the safety net.`,
+            };
+        case 'git-missing':
+            if (options.allowDirty) {
+                return {
+                    ok: true,
+                    status,
+                    message: `git CLI not found; running with --allow-dirty. Post-flight rollback is disabled.`,
+                };
+            }
+            return {
+                ok: false,
+                status,
+                message: `git CLI not found on PATH. Revise requires git for its post-flight rollback safety net. Install git, or re-run with --allow-dirty to opt out.`,
+            };
+        default: {
+            const _exhaustive = status;
+            throw new Error(`unhandled GitTreeStatus: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}
+/**
+ * Restore a set of paths from HEAD — the primitive the post-flight
+ * rollback invokes when graph integrity breaks after writes. Paths are
+ * relative to `projectDir`. Empty list is a no-op.
+ */
+export async function checkoutPaths(projectDir, relativePaths) {
+    if (relativePaths.length === 0)
+        return;
+    await execFileAsync('git', ['checkout', '--', ...relativePaths], {
+        cwd: projectDir,
+        maxBuffer: GIT_MAX_BUFFER,
+    });
+}
+//# sourceMappingURL=git-service.js.map

package/dist/services/git-service.js.map

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

package/dist/services/graph-integrity.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Read-only artifact-graph integrity check for `planr revise` post-flight.
+ *
+ * Detects broken parent/child links after a revise run so the caller can
+ * trigger automatic rollback if the writes left the tree inconsistent. This
+ * is deliberately narrower than `planr sync`: it does not fix anything, does
+ * not write to the logger, and only looks at the relationships revise might
+ * have perturbed (parent-id frontmatter fields on features, stories, tasks).
+ *
+ * Why a separate module: keeps revise decoupled from the `sync` command's
+ * repair logic, which has different invariants (fixes links, prompts the
+ * user, etc.). The check here is a pure data function.
+ */
+import type { ArtifactType, OpenPlanrConfig } from '../models/types.js';
+export interface GraphIntegrityIssue {
+    childId: string;
+    childType: ArtifactType;
+    childPath: string;
+    parentField: 'epicId' | 'featureId' | 'storyId';
+    parentId: string;
+    reason: 'missing-parent' | 'parent-type-mismatch';
+}
+export interface GraphIntegrityReport {
+    ok: boolean;
+    issues: GraphIntegrityIssue[];
+}
+/**
+ * Walk every feature/story/task and verify its parent-id frontmatter
+ * resolves to an existing parent artifact of the correct type. Missing
+ * parent-id fields are tolerated (some tasks legitimately attach at
+ * feature level, for example) — only *broken* non-empty references are
+ * reported.
+ */
+export declare function checkGraphIntegrity(projectDir: string, config: OpenPlanrConfig): Promise<GraphIntegrityReport>;
+//# sourceMappingURL=graph-integrity.d.ts.map

package/dist/services/graph-integrity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-integrity.d.ts","sourceRoot":"","sources":["../../src/services/graph-integrity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGxE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,YAAY,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,gBAAgB,GAAG,sBAAsB,CAAC;CACnD;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,mBAAmB,EAAE,CAAC;CAC/B;AAcD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,oBAAoB,CAAC,CA0B/B"}

package/dist/services/graph-integrity.js

@@ -0,0 +1,53 @@
+/**
+ * Read-only artifact-graph integrity check for `planr revise` post-flight.
+ *
+ * Detects broken parent/child links after a revise run so the caller can
+ * trigger automatic rollback if the writes left the tree inconsistent. This
+ * is deliberately narrower than `planr sync`: it does not fix anything, does
+ * not write to the logger, and only looks at the relationships revise might
+ * have perturbed (parent-id frontmatter fields on features, stories, tasks).
+ *
+ * Why a separate module: keeps revise decoupled from the `sync` command's
+ * repair logic, which has different invariants (fixes links, prompts the
+ * user, etc.). The check here is a pure data function.
+ */
+import { listArtifacts, readArtifact } from './artifact-service.js';
+const CHECKS = [
+    { childType: 'feature', parentField: 'epicId', parentType: 'epic' },
+    { childType: 'story', parentField: 'featureId', parentType: 'feature' },
+    { childType: 'task', parentField: 'storyId', parentType: 'story' },
+];
+/**
+ * Walk every feature/story/task and verify its parent-id frontmatter
+ * resolves to an existing parent artifact of the correct type. Missing
+ * parent-id fields are tolerated (some tasks legitimately attach at
+ * feature level, for example) — only *broken* non-empty references are
+ * reported.
+ */
+export async function checkGraphIntegrity(projectDir, config) {
+    const issues = [];
+    for (const spec of CHECKS) {
+        const children = await listArtifacts(projectDir, config, spec.childType);
+        for (const childRow of children) {
+            const child = await readArtifact(projectDir, config, spec.childType, childRow.id);
+            if (!child)
+                continue;
+            const parentId = child.data[spec.parentField];
+            if (!parentId)
+                continue; // optional ref — not a broken link
+            const parent = await readArtifact(projectDir, config, spec.parentType, parentId);
+            if (!parent) {
+                issues.push({
+                    childId: childRow.id,
+                    childType: spec.childType,
+                    childPath: child.filePath,
+                    parentField: spec.parentField,
+                    parentId,
+                    reason: 'missing-parent',
+                });
+            }
+        }
+    }
+    return { ok: issues.length === 0, issues };
+}
+//# sourceMappingURL=graph-integrity.js.map

package/dist/services/graph-integrity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-integrity.js","sourceRoot":"","sources":["../../src/services/graph-integrity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAsBpE,MAAM,MAAM,GAAgB;IAC1B,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE;IACnE,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE;IACvE,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE;CACnE,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,UAAkB,EAClB,MAAuB;IAEvB,MAAM,MAAM,GAA0B,EAAE,CAAC;IAEzC,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACzE,KAAK,MAAM,QAAQ,IAAI,QAAQ,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;YAClF,IAAI,CAAC,KAAK;gBAAE,SAAS;YACrB,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAuB,CAAC;YACpE,IAAI,CAAC,QAAQ;gBAAE,SAAS,CAAC,mCAAmC;YAE5D,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;YACjF,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,CAAC,IAAI,CAAC;oBACV,OAAO,EAAE,QAAQ,CAAC,EAAE;oBACpB,SAAS,EAAE,IAAI,CAAC,SAAS;oBACzB,SAAS,EAAE,KAAK,CAAC,QAAQ;oBACzB,WAAW,EAAE,IAAI,CAAC,WAAW;oBAC7B,QAAQ;oBACR,MAAM,EAAE,gBAAgB;iBACzB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;AAC7C,CAAC"}

package/dist/services/linear/body-formatters.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Pure markdown body/description formatters for Linear issues and projects.
+ *
+ * Every function here takes local OpenPlanr artifact data and returns the
+ * string that goes into the Linear entity's `description` / `title` field.
+ * Stateless + side-effect free except for `buildMergedTaskListBody`, which
+ * reads task files via the artifact-service to assemble a feature's
+ * aggregated checkbox body.
+ */
+import { type ParsedSubtask } from '../../agents/task-parser.js';
+import type { Epic, Feature, OpenPlanrConfig, UserStory } from '../../models/types.js';
+/** Convert an unknown frontmatter value to an optional string at the type boundary. */
+export declare function toOptionalString(v: unknown): string | undefined;
+/** Convert an unknown frontmatter value to an optional array of strings. */
+export declare function toOptionalStringArray(v: unknown): string[] | undefined;
+/** Epic → Linear Project `description` (markdown). Skips whitespace-only sections. */
+export declare function buildEpicProjectDescription(epic: Epic): string;
+/** Feature → Linear issue body (overview + functional requirements bullets). */
+export declare function buildFeatureIssueBody(feature: Feature): string;
+/**
+ * User story → Linear sub-issue body.
+ *
+ * Composes, in order:
+ *   1. The "As a / I want / So that" sentence — only when all three fields
+ *      are present (otherwise rendering with blanks produces visible
+ *      garbage in Linear).
+ *   2. The frontmatter `acceptanceCriteria` prose — if set.
+ *   3. The Gherkin scenarios from `<storyId>-gherkin.feature` — if the
+ *      caller provides them. Stories in the OpenPlanr convention store
+ *      their real acceptance criteria as Gherkin in a sibling `.feature`
+ *      file; without this, the Linear issue was empty for every story
+ *      that followed the convention.
+ */
+export declare function buildStoryIssueBody(story: UserStory, gherkinContent?: string | null): string;
+/** Render parsed task lines to markdown checkboxes (Linear description). */
+export declare function formatTaskCheckboxBody(parsed: ParsedSubtask[]): string;
+/**
+ * Build a merged task-list body for a feature — concatenates every task
+ * artifact whose `featureId` matches, parses its checkboxes, renders them,
+ * and (when multiple files exist) prefixes each section with its task id
+ * as an `## h2`. Returns `''` when there's nothing to sync.
+ */
+export declare function buildMergedTaskListBody(projectDir: string, config: OpenPlanrConfig, featureId: string, taskFiles: Array<{
+    id: string;
+    title: string;
+}>): Promise<string>;
+/**
+ * Extract the markdown body of a standalone artifact (QT / BL) for pushing
+ * to Linear as an issue description.
+ *
+ * Strips:
+ *   - the frontmatter block (YAML between the `---` markers)
+ *   - the top-level `# <ID>: <title>` heading (Linear shows the title
+ *     separately, so repeating it in the description is noise)
+ *
+ * Everything else — prose, sub-headings, checkbox lists — is preserved
+ * verbatim. Linear renders standard markdown, so checkboxes stay checkboxes,
+ * `## sections` stay sections, links stay clickable.
+ */
+export declare function buildStandaloneArtifactBody(raw: string, id: string): string;
+/**
+ * Backlog item → Linear issue body. Priority + tags + description + optional
+ * acceptance criteria + notes. Accepts the generic frontmatter record shape
+ * because backlog items aren't currently loaded via a typed interface.
+ */
+export declare function buildBacklogItemBody(bl: {
+    frontmatter: Record<string, unknown>;
+}): string;
+//# sourceMappingURL=body-formatters.d.ts.map

package/dist/services/linear/body-formatters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-formatters.d.ts","sourceRoot":"","sources":["../../../src/services/linear/body-formatters.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAqB,MAAM,6BAA6B,CAAC;AACpF,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGvF,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE/D;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,EAAE,GAAG,SAAS,CAItE;AAED,sFAAsF;AACtF,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAc9D;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAS9D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAc5F;AAED,4EAA4E;AAC5E,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,CAWtE;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GAC9C,OAAO,CAAC,MAAM,CAAC,CAqBjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAgB3E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,MAAM,CAgBzF"}

package/dist/services/linear/body-formatters.js

@@ -0,0 +1,183 @@
+/**
+ * Pure markdown body/description formatters for Linear issues and projects.
+ *
+ * Every function here takes local OpenPlanr artifact data and returns the
+ * string that goes into the Linear entity's `description` / `title` field.
+ * Stateless + side-effect free except for `buildMergedTaskListBody`, which
+ * reads task files via the artifact-service to assemble a feature's
+ * aggregated checkbox body.
+ */
+import { parseTaskMarkdown } from '../../agents/task-parser.js';
+import { readArtifact, readArtifactRaw } from '../artifact-service.js';
+/** Convert an unknown frontmatter value to an optional string at the type boundary. */
+export function toOptionalString(v) {
+    return typeof v === 'string' ? v : undefined;
+}
+/** Convert an unknown frontmatter value to an optional array of strings. */
+export function toOptionalStringArray(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const out = v.filter((item) => typeof item === 'string');
+    return out.length > 0 ? out : undefined;
+}
+/** Epic → Linear Project `description` (markdown). Skips whitespace-only sections. */
+export function buildEpicProjectDescription(epic) {
+    const lines = [];
+    const section = (label, value) => {
+        const trimmed = value?.trim();
+        if (trimmed)
+            lines.push(`**${label}**\n\n${trimmed}`);
+    };
+    section('Business value', epic.businessValue);
+    section('Problem', epic.problemStatement);
+    section('Solution', epic.solutionOverview);
+    section('Success criteria', epic.successCriteria);
+    section('Target users', epic.targetUsers);
+    section('Risks', epic.risks);
+    section('Dependencies', epic.dependencies);
+    return lines.join('\n\n');
+}
+/** Feature → Linear issue body (overview + functional requirements bullets). */
+export function buildFeatureIssueBody(feature) {
+    const lines = [feature.overview?.trim() || ''];
+    if (feature.functionalRequirements?.length) {
+        lines.push('**Functional requirements**');
+        for (const r of feature.functionalRequirements) {
+            lines.push(`- ${r}`);
+        }
+    }
+    return lines.filter(Boolean).join('\n\n');
+}
+/**
+ * User story → Linear sub-issue body.
+ *
+ * Composes, in order:
+ *   1. The "As a / I want / So that" sentence — only when all three fields
+ *      are present (otherwise rendering with blanks produces visible
+ *      garbage in Linear).
+ *   2. The frontmatter `acceptanceCriteria` prose — if set.
+ *   3. The Gherkin scenarios from `<storyId>-gherkin.feature` — if the
+ *      caller provides them. Stories in the OpenPlanr convention store
+ *      their real acceptance criteria as Gherkin in a sibling `.feature`
+ *      file; without this, the Linear issue was empty for every story
+ *      that followed the convention.
+ */
+export function buildStoryIssueBody(story, gherkinContent) {
+    const role = story.role?.trim();
+    const goal = story.goal?.trim();
+    const benefit = story.benefit?.trim();
+    const ac = story.acceptanceCriteria?.trim();
+    const gherkin = gherkinContent?.trim();
+    const hasFullUserStoryLine = Boolean(role && goal && benefit);
+    const sections = [];
+    if (hasFullUserStoryLine) {
+        sections.push(`As a **${role}**, I want **${goal}** so that **${benefit}**.`);
+    }
+    if (ac)
+        sections.push(`**Acceptance criteria**\n\n${ac}`);
+    if (gherkin)
+        sections.push(`**Gherkin scenarios**\n\n\`\`\`gherkin\n${gherkin}\n\`\`\``);
+    return sections.join('\n\n');
+}
+/** Render parsed task lines to markdown checkboxes (Linear description). */
+export function formatTaskCheckboxBody(parsed) {
+    if (parsed.length === 0)
+        return '';
+    return parsed
+        .map((p) => {
+        const mark = p.done ? 'x' : ' ';
+        if (p.depth === 0) {
+            return `- [${mark}] **${p.id}** ${p.title}`;
+        }
+        return `  - [${mark}] ${p.id} ${p.title}`;
+    })
+        .join('\n');
+}
+/**
+ * Build a merged task-list body for a feature — concatenates every task
+ * artifact whose `featureId` matches, parses its checkboxes, renders them,
+ * and (when multiple files exist) prefixes each section with its task id
+ * as an `## h2`. Returns `''` when there's nothing to sync.
+ */
+export async function buildMergedTaskListBody(projectDir, config, featureId, taskFiles) {
+    const sections = [];
+    const sorted = [...taskFiles].sort((a, b) => a.id.localeCompare(b.id, undefined, { numeric: true }));
+    for (const tf of sorted) {
+        const raw = await readArtifactRaw(projectDir, config, 'task', tf.id);
+        if (!raw)
+            continue;
+        const data = (await readArtifact(projectDir, config, 'task', tf.id))?.data;
+        const fId = toOptionalString(data?.featureId);
+        if (fId !== featureId)
+            continue;
+        const parsed = parseTaskMarkdown(raw);
+        if (parsed.length === 0)
+            continue;
+        const body = formatTaskCheckboxBody(parsed);
+        if (taskFiles.length > 1) {
+            sections.push(`## ${tf.id}\n\n${body}`);
+        }
+        else {
+            sections.push(body);
+        }
+    }
+    return sections.join('\n\n');
+}
+/**
+ * Extract the markdown body of a standalone artifact (QT / BL) for pushing
+ * to Linear as an issue description.
+ *
+ * Strips:
+ *   - the frontmatter block (YAML between the `---` markers)
+ *   - the top-level `# <ID>: <title>` heading (Linear shows the title
+ *     separately, so repeating it in the description is noise)
+ *
+ * Everything else — prose, sub-headings, checkbox lists — is preserved
+ * verbatim. Linear renders standard markdown, so checkboxes stay checkboxes,
+ * `## sections` stay sections, links stay clickable.
+ */
+export function buildStandaloneArtifactBody(raw, id) {
+    // Strip frontmatter if present.
+    let body = raw;
+    const fmMatch = /^---[^\S\r\n]*\r?\n[\s\S]*?\r?\n---[^\S\r\n]*\r?\n?/.exec(raw);
+    if (fmMatch) {
+        body = raw.slice(fmMatch[0].length);
+    }
+    // Drop leading blank lines — markdown files typically have a blank line
+    // between the frontmatter's closing `---` and the first `#` heading.
+    body = body.replace(/^\s*\r?\n/, '').trimStart();
+    // Strip a single top-level `# <ID>:...` or `# <anything>` heading at the
+    // start of the body, plus the blank line that typically follows it.
+    const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const titleHeadingRegex = new RegExp(`^#\\s+(?:${escapedId}:\\s*)?.*\\r?\\n(?:\\r?\\n)?`);
+    body = body.replace(titleHeadingRegex, '');
+    return body.trimEnd();
+}
+/**
+ * Backlog item → Linear issue body. Priority + tags + description + optional
+ * acceptance criteria + notes. Accepts the generic frontmatter record shape
+ * because backlog items aren't currently loaded via a typed interface.
+ */
+export function buildBacklogItemBody(bl) {
+    const fm = bl.frontmatter;
+    const lines = [];
+    const priority = toOptionalString(fm.priority);
+    if (priority)
+        lines.push(`**Priority:** ${priority}`);
+    if (Array.isArray(fm.tags) && fm.tags.length > 0) {
+        const tags = fm.tags.filter((t) => typeof t === 'string');
+        if (tags.length)
+            lines.push(`**Tags:** ${tags.join(', ')}`);
+    }
+    const description = toOptionalString(fm.description);
+    if (description)
+        lines.push(description.trim());
+    const ac = toOptionalString(fm.acceptanceCriteria);
+    if (ac)
+        lines.push(`**Acceptance criteria**\n\n${ac.trim()}`);
+    const notes = toOptionalString(fm.notes);
+    if (notes)
+        lines.push(`**Notes**\n\n${notes.trim()}`);
+    return lines.join('\n\n');
+}
+//# sourceMappingURL=body-formatters.js.map

package/dist/services/linear/body-formatters.js.map

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

package/dist/services/linear/constants.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Linear integration constants + id-shape validators + input-safety helpers.
+ *
+ * All field-limit values here are enforced at the SDK-wrapper layer in
+ * `src/services/linear-service.ts` so that every caller gets the guard for
+ * free. Shape validators (`isLikelyLinear*Id`) fence off stale frontmatter
+ * before it reaches the Linear API.
+ */
+/** Credential-service provider key under which the Linear PAT is stored. */
+export declare const LINEAR_CREDENTIAL_KEY: "linear";
+/**
+ * Linear's backend enforces per-field length limits on every create/update
+ * mutation. Defend at the SDK-wrapper layer so callers don't have to think
+ * about them. Names / titles: confirmed or best-known caps; descriptions:
+ * conservative floors well under Linear's real ceilings (markdown + HTML
+ * are both accepted; real limits are in the tens of thousands).
+ */
+export declare const LINEAR_FIELD_LIMITS: {
+    /** ProjectMilestone.name — confirmed 80 by `Argument Validation Error`. */
+    readonly milestoneName: 80;
+    /** IssueLabel.name — Linear team labels cap ~64 chars. */
+    readonly labelName: 64;
+    /** Project.name — generous cap. */
+    readonly projectName: 256;
+    /** Issue.title — Linear issue title cap ~255. */
+    readonly issueTitle: 255;
+    /** Project.description — conservative floor; real Linear ceiling is higher. */
+    readonly projectDescription: 50000;
+    /** ProjectMilestone.description. */
+    readonly milestoneDescription: 50000;
+    /** IssueLabel.description — labels rarely need long descriptions. */
+    readonly labelDescription: 500;
+    /** Issue.description (markdown body). */
+    readonly issueDescription: 65000;
+};
+/**
+ * Truncate a string to Linear's character limit for a given field. Logs a
+ * warning on truncation so the operator can spot it in the push output.
+ */
+export declare function truncateForLinear(value: string, maxLen: number, fieldLabel: string): string;
+/**
+ * Non-empty guard for required Linear name/title fields. Fails fast with an
+ * actionable message before the API would reject the call.
+ */
+export declare function requireNonEmpty(value: string | null | undefined, fieldLabel: string): string;
+/**
+ * Heuristic: Linear workflow state id (uuid) vs human-readable state name.
+ * The `/i` flag is intentional — Linear's API canonicalizes UUIDs to
+ * lowercase, but defensive acceptance of uppercase hex matches RFC 4122
+ * and protects against tools that normalize differently.
+ */
+export declare function isLikelyLinearWorkflowStateId(s: string): boolean;
+/**
+ * Validate that a value plausibly identifies a Linear issue. Two valid shapes:
+ *   1. UUIDv4 (e.g. `9b2f4c3e-...`) — canonical API form
+ *   2. Linear identifier (e.g. `ENG-42`) — human-readable, also accepted by `client.issue()`
+ * Anything else is treated as stale/corrupted frontmatter and skipped before
+ * hitting the API.
+ */
+export declare function isLikelyLinearIssueId(s: string): boolean;
+//# sourceMappingURL=constants.d.ts.map

package/dist/services/linear/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/services/linear/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,EAAG,QAAiB,CAAC;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;IAC9B,2EAA2E;;IAE3E,0DAA0D;;IAE1D,mCAAmC;;IAEnC,iDAAiD;;IAEjD,+EAA+E;;IAE/E,oCAAoC;;IAEpC,qEAAqE;;IAErE,yCAAyC;;CAEjC,CAAC;AAEX;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAQ3F;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAQ5F;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAIhE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAKxD"}