p-dev-harness 0.3.0

package/dist/setup/vercel-setup-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel-setup-summary.js","sourceRoot":"","sources":["../../src/setup/vercel-setup-summary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAE5E,OAAO,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAUzD,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,GAAY;IAEZ,MAAM,KAAK,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,WAAW,GAAG,MAAM,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACrD,MAAM,YAAY,GAAG,MAAM,0BAA0B,CAAC,GAAG,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,YAAY,EAAE,MAAM,CAAC;IAEpC,MAAM,SAAS,GAAG,2BAA2B,CAAC;QAC5C,SAAS,EAAE,MAAM,EAAE,SAAS;QAC5B,aAAa,EAAE,MAAM,EAAE,aAAa;QACpC,UAAU,EAAE,MAAM,EAAE,UAAU;QAC9B,iBAAiB,EAAE,MAAM,EAAE,iBAAiB;QAC5C,mBAAmB,EAAE,MAAM,EAAE,cAAc;QAC3C,qBAAqB,EAAE,MAAM,EAAE,qBAAqB;QACpD,mBAAmB,EAAE,MAAM,EAAE,mBAAmB;QAChD,0BAA0B,EAAE,MAAM,EAAE,0BAA0B;QAC9D,cAAc,EAAE,MAAM,EAAE,cAAc;KACvC,CAAC,CAAC;IAEH,OAAO;QACL,YAAY;QACZ,qBAAqB,EAAE,OAAO,CAAC,WAAW,EAAE,QAAQ,CAAC,YAAY,CAAC;QAClE,sBAAsB,EAAE,OAAO,CAAC,WAAW,EAAE,QAAQ,CAAC,cAAc,CAAC;QACrE,SAAS;QACT,aAAa,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO;KAC7C,CAAC;AACJ,CAAC"}

package/dist/setup/vercel-webhook-probe.d.ts

@@ -0,0 +1,17 @@
+export interface VercelSignedProbeEvidence {
+    passed: boolean;
+    statusCode?: number;
+    result: "accepted_ignored" | "auth_failed" | "unreachable" | "protection_redirect" | "error";
+    reason?: string;
+    probedAt: string;
+    webhookHost?: string;
+    webhookPath?: string;
+}
+export interface RunSignedWebhookProbeInput {
+    webhookUrl: string;
+    secret: string;
+    nowMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export declare function runSignedWebhookProbe(input: RunSignedWebhookProbeInput): Promise<VercelSignedProbeEvidence>;
+//# sourceMappingURL=vercel-webhook-probe.d.ts.map

package/dist/setup/vercel-webhook-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel-webhook-probe.d.ts","sourceRoot":"","sources":["../../src/setup/vercel-webhook-probe.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,kBAAkB,GAAG,aAAa,GAAG,aAAa,GAAG,qBAAqB,GAAG,OAAO,CAAC;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAoCD,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,yBAAyB,CAAC,CAyGpC"}

package/dist/setup/vercel-webhook-probe.js

@@ -0,0 +1,125 @@
+import { computeLinearSignature } from "../webhook/verify.js";
+function redactWebhookLocation(webhookUrl) {
+    try {
+        const url = new URL(webhookUrl);
+        return {
+            webhookHost: url.host,
+            webhookPath: url.pathname,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function buildIgnoredProbePayload(nowMs) {
+    return JSON.stringify({
+        action: "create",
+        type: "Comment",
+        webhookTimestamp: nowMs,
+        data: {
+            id: "harness-setup-probe",
+        },
+    });
+}
+function isVercelProtectionRedirect(response) {
+    if (response.status !== 302 && response.status !== 307 && response.status !== 308) {
+        return false;
+    }
+    const location = response.headers.get("location") ?? "";
+    return /vercel\.com\/sso-api/i.test(location);
+}
+export async function runSignedWebhookProbe(input) {
+    const nowMs = input.nowMs ?? Date.now();
+    const location = redactWebhookLocation(input.webhookUrl);
+    const rawBody = buildIgnoredProbePayload(nowMs);
+    const signature = computeLinearSignature(input.secret, rawBody);
+    const fetchImpl = input.fetchImpl ?? fetch;
+    try {
+        const response = await fetchImpl(input.webhookUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "linear-signature": signature,
+                "linear-timestamp": String(nowMs),
+                "linear-event": "Comment",
+                "linear-delivery": `harness-setup-probe-${nowMs}`,
+            },
+            body: rawBody,
+            redirect: "manual",
+        });
+        if (isVercelProtectionRedirect(response)) {
+            return {
+                passed: false,
+                statusCode: response.status,
+                result: "protection_redirect",
+                reason: "Vercel Deployment Protection redirected the webhook endpoint. Disable protection for /api/linear-webhook or allow public access before verifying the bridge.",
+                probedAt: new Date(nowMs).toISOString(),
+                ...location,
+            };
+        }
+        let body = null;
+        try {
+            body = (await response.json());
+        }
+        catch {
+            return {
+                passed: false,
+                statusCode: response.status,
+                result: "error",
+                reason: "Webhook endpoint did not return JSON.",
+                probedAt: new Date(nowMs).toISOString(),
+                ...location,
+            };
+        }
+        if (response.status === 401) {
+            return {
+                passed: false,
+                statusCode: response.status,
+                result: "auth_failed",
+                reason: body.error ?? "invalid_signature",
+                probedAt: new Date(nowMs).toISOString(),
+                ...location,
+            };
+        }
+        if (response.status === 404) {
+            return {
+                passed: false,
+                statusCode: response.status,
+                result: "unreachable",
+                reason: "Webhook route was not found on the production deployment.",
+                probedAt: new Date(nowMs).toISOString(),
+                ...location,
+            };
+        }
+        if (response.status === 200 &&
+            body.accepted === false &&
+            typeof body.reason === "string") {
+            return {
+                passed: true,
+                statusCode: response.status,
+                result: "accepted_ignored",
+                reason: body.reason,
+                probedAt: new Date(nowMs).toISOString(),
+                ...location,
+            };
+        }
+        return {
+            passed: false,
+            statusCode: response.status,
+            result: "error",
+            reason: "Signed probe was not authentication-accepted and business-ignored.",
+            probedAt: new Date(nowMs).toISOString(),
+            ...location,
+        };
+    }
+    catch {
+        return {
+            passed: false,
+            result: "unreachable",
+            reason: "Webhook endpoint could not be reached for signed probe verification.",
+            probedAt: new Date(nowMs).toISOString(),
+            ...location,
+        };
+    }
+}
+//# sourceMappingURL=vercel-webhook-probe.js.map

package/dist/setup/vercel-webhook-probe.js.map

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

package/dist/setup/workflow-install-merge-errors.d.ts

@@ -0,0 +1,12 @@
+import type { WorkflowInstallBlockedCategory } from "./target-workflow-finalization-types.js";
+export declare function classifyWorkflowInstallMergeRejection(input: {
+    error: unknown;
+    mergeableState?: string | null;
+    message?: string;
+}): {
+    category: WorkflowInstallBlockedCategory;
+    waiting: boolean;
+    message: string;
+};
+export declare function blockedCategoryMessage(category: WorkflowInstallBlockedCategory): string;
+//# sourceMappingURL=workflow-install-merge-errors.d.ts.map

package/dist/setup/workflow-install-merge-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-install-merge-errors.d.ts","sourceRoot":"","sources":["../../src/setup/workflow-install-merge-errors.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,yCAAyC,CAAC;AAE9F,wBAAgB,qCAAqC,CAAC,KAAK,EAAE;IAC3D,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG;IACF,QAAQ,EAAE,8BAA8B,CAAC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB,CA0HA;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,8BAA8B,GACvC,MAAM,CA2BR"}

package/dist/setup/workflow-install-merge-errors.js

@@ -0,0 +1,130 @@
+import { GitHubApiError } from "../github/client.js";
+import { classifyMergeError } from "../github/merge-result.js";
+export function classifyWorkflowInstallMergeRejection(input) {
+    const apiMessage = (input.message ??
+        (input.error instanceof Error ? input.error.message : String(input.error))).toLowerCase();
+    if (input.error instanceof GitHubApiError) {
+        if (input.error.status === 401 || input.error.status === 403) {
+            if (apiMessage.includes("review") ||
+                apiMessage.includes("approval") ||
+                apiMessage.includes("required reviewers")) {
+                return {
+                    category: "review-required",
+                    waiting: false,
+                    message: "GitHub requires human review before this workflow install PR can merge.",
+                };
+            }
+            return {
+                category: "permission-denied",
+                waiting: false,
+                message: "The setup token does not have permission to merge this workflow install PR.",
+            };
+        }
+        if (input.error.status === 405) {
+            if (classifyMergeError(input.error) === "pr_already_merged") {
+                return {
+                    category: "merge-api-failure",
+                    waiting: false,
+                    message: "Workflow install PR was already merged.",
+                };
+            }
+        }
+        if (input.error.status === 409) {
+            return {
+                category: "merge-conflict",
+                waiting: false,
+                message: "The workflow install PR has merge conflicts that require manual resolution.",
+            };
+        }
+        if (input.error.status === 422) {
+            if (apiMessage.includes("merge queue") ||
+                apiMessage.includes("queued for merge")) {
+                return {
+                    category: "merge-queue-required",
+                    waiting: false,
+                    message: "This repository requires merge queue handling that onboarding does not support automatically.",
+                };
+            }
+            if (apiMessage.includes("head sha") ||
+                apiMessage.includes("expected head")) {
+                return {
+                    category: "mergeability-pending",
+                    waiting: true,
+                    message: "The workflow install PR head changed during finalization. Revalidating before merge.",
+                };
+            }
+            if (apiMessage.includes("required status") ||
+                apiMessage.includes("not mergeable") ||
+                apiMessage.includes("checks")) {
+                return {
+                    category: "checks-pending",
+                    waiting: true,
+                    message: "GitHub is still waiting for required checks on the workflow install PR.",
+                };
+            }
+            if (apiMessage.includes("review")) {
+                return {
+                    category: "review-required",
+                    waiting: false,
+                    message: "GitHub requires human review before this workflow install PR can merge.",
+                };
+            }
+        }
+    }
+    const state = input.mergeableState?.toLowerCase() ?? "";
+    if (state === "dirty") {
+        return {
+            category: "merge-conflict",
+            waiting: false,
+            message: "The workflow install PR has merge conflicts that require manual resolution.",
+        };
+    }
+    if (state === "behind") {
+        return {
+            category: "branch-behind",
+            waiting: true,
+            message: "The workflow install branch is behind the production branch.",
+        };
+    }
+    if (state === "blocked") {
+        return {
+            category: "review-required",
+            waiting: false,
+            message: "Branch protection or review rules are blocking automatic merge of the workflow install PR.",
+        };
+    }
+    return {
+        category: "merge-api-failure",
+        waiting: false,
+        message: "GitHub rejected the workflow install PR merge request.",
+    };
+}
+export function blockedCategoryMessage(category) {
+    switch (category) {
+        case "checks-pending":
+            return "Waiting for GitHub checks on the workflow install PR.";
+        case "checks-failing":
+            return "Required checks failed on the workflow install PR.";
+        case "mergeability-pending":
+            return "GitHub is still computing mergeability for the workflow install PR.";
+        case "branch-behind":
+            return "Updating the workflow install branch to match production.";
+        case "review-required":
+            return "Human review is required before the workflow install PR can merge.";
+        case "permission-denied":
+            return "The setup token cannot merge the workflow install PR.";
+        case "merge-conflict":
+            return "The workflow install PR has merge conflicts.";
+        case "unexpected-pr-content":
+            return "The workflow install PR contains unexpected changes.";
+        case "merge-queue-required":
+            return "This repository requires merge queue handling.";
+        case "merge-api-failure":
+            return "GitHub rejected the workflow install merge request.";
+        case "verification-failed":
+            return "The workflow was merged but production verification has not succeeded yet.";
+        default:
+            return "Workflow install finalization is blocked.";
+    }
+}
+//# sourceMappingURL=workflow-install-merge-errors.js.map

package/dist/setup/workflow-install-merge-errors.js.map

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

package/dist/types/parsed-issue.d.ts

@@ -0,0 +1,9 @@
+export interface ParsedIssue {
+    targetRepoRaw?: string;
+    task: string;
+    acceptanceCriteria: string[];
+    outOfScope: string[];
+    validationExpectations?: string;
+    parseErrors: string[];
+}
+//# sourceMappingURL=parsed-issue.d.ts.map

package/dist/types/parsed-issue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parsed-issue.d.ts","sourceRoot":"","sources":["../../src/types/parsed-issue.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB"}

package/dist/types/parsed-issue.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=parsed-issue.js.map

package/dist/types/parsed-issue.js.map

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

package/dist/types/run.d.ts

@@ -0,0 +1,46 @@
+export type RunPhase = "planning" | "implementation" | "handoff" | "revision" | "merge" | "production_sync" | "none";
+export type FinalOutcome = "success" | "failed" | "skipped" | "duplicate";
+export type ErrorClassification = "ambiguous_issue" | "missing_target_repo" | "unknown_repo_denied" | "wrong_status" | "duplicate_phase_completed" | "linear_auth_failure" | "cursor_api_failure" | "cursor_run_failed" | "cursor_run_timeout" | "linear_write_failure" | "agent_policy_violation" | "missing_planning_comment" | "validation_failed" | "pr_not_created" | "branch_without_pr" | "wrong_target_repo" | "wrong_pr_target" | "base_branch_missing" | "wrong_pr_base_branch" | "github_auth_failure" | "github_api_failure" | "repair_head_branch_write_denied" | "repair_validation_failed" | "repair_ambiguous" | "repair_scope_violation" | "repair_requires_product_judgment" | "repair_base_branch_violation" | "missing_implementation_marker" | "missing_implementation_pr" | "missing_merge_metadata" | "production_not_promoted" | "missing_pr_url" | "pr_closed" | "preview_not_found" | "checks_failing" | "missing_handoff_marker" | "missing_pm_feedback" | "missing_branch" | "revision_pr_mismatch" | "cursor_branch_attach_failure" | "missing_merge_source_marker" | "pr_already_merged" | "checks_pending" | "checks_unknown" | "github_merge_failure" | "deployment_not_found" | "recovery_handoff" | "implementation_in_progress" | null;
+export interface RunManifest {
+    runId: string;
+    issueKey: string;
+    phase: RunPhase;
+    phaseInferredFromStatus: string | null;
+    linearStatusBefore: string | null;
+    linearStatusAfter: string | null;
+    targetRepo: string | null;
+    baseBranch: string | null;
+    resolutionSource: "explicit" | "project" | "team" | null;
+    dryRun: boolean;
+    finalOutcome: FinalOutcome;
+    errorClassification: ErrorClassification;
+    startedAt: string;
+    finishedAt: string;
+    milestone: string;
+    promptVersion: string | null;
+    cursorAgentId: string | null;
+    cursorRunId: string | null;
+    branch: string | null;
+    prUrl: string | null;
+    previewUrl: string | null;
+    validationSummary: string | null;
+    changedFiles: string[] | null;
+    checkSummary: string | null;
+    previousImplementationRunId: string | null;
+    previousHandoffRunId: string | null;
+    pmFeedbackCommentId: string | null;
+    previousRevisionRunId: string | null;
+    mergeCommitSha: string | null;
+    mergeMethod: string | null;
+    mergedAt: string | null;
+    deploymentUrl: string | null;
+    model: string | null;
+}
+export type RunEventName = "run_started" | "config_loaded" | "issue_fetched" | "issue_loaded_from_fixture" | "issue_parsed" | "repo_resolved" | "repo_resolution_failed" | "phase_inferred" | "idempotency_skip" | "planning_comment_loaded" | "implementation_comment_loaded" | "linear_status_changed" | "linear_comment_posted" | "phase_start_comment_posted" | "cursor_agent_created" | "cursor_event" | "cursor_run_poll_fallback" | "cursor_run_finished" | "cursor_run_cancelled" | "cursor_cancel_unavailable" | "cursor_run_cancel_failed" | "git_result_captured" | "pr_captured" | "validation_completed" | "github_pr_inspected" | "preview_poll_started" | "preview_captured" | "preview_not_found" | "handoff_comment_posted" | "handoff_comment_loaded" | "pm_feedback_loaded" | "revision_comment_posted" | "revision_pr_validated" | "merge_source_comment_loaded" | "merge_checks_evaluated" | "repair_started" | "repair_deterministic_update_attempted" | "repair_agent_started" | "repair_completed" | "repair_failed" | "repair_returned_to_merge" | "github_pr_marked_ready" | "github_merge_requested" | "github_merge_completed" | "deployment_poll_started" | "deployment_poll_skipped" | "deployment_captured" | "deployment_not_found" | "merge_comment_posted" | "merge_recovery_written" | "run_finished";
+export interface RunEvent {
+    ts: string;
+    level: "info" | "warn" | "error";
+    event: RunEventName;
+    data?: Record<string, unknown>;
+}
+//# sourceMappingURL=run.d.ts.map

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

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

package/dist/types/run.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run.js.map

package/dist/types/run.js.map

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

package/dist/validate/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const NARROW_TASK_MAX_LENGTH = 240;
+export declare const NARROW_AC_MAX_COUNT = 7;
+//# sourceMappingURL=constants.d.ts.map

package/dist/validate/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/validate/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,mBAAmB,IAAI,CAAC"}

package/dist/validate/constants.js

@@ -0,0 +1,3 @@
+export const NARROW_TASK_MAX_LENGTH = 240;
+export const NARROW_AC_MAX_COUNT = 7;
+//# sourceMappingURL=constants.js.map

package/dist/validate/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/validate/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAC1C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC"}

package/dist/validate/issue.d.ts

@@ -0,0 +1,15 @@
+import type { HarnessConfig } from "../config/types.js";
+import type { IntendedPhase, IssueValidationResult, ValidateIssueOptions } from "./types.js";
+export declare function computeIssueValidation(description: string, context: {
+    projectName?: string;
+    teamName?: string;
+}, config: HarnessConfig, options: {
+    intendedPhase?: IntendedPhase;
+    hasPlanningMarker?: boolean;
+    planningMarkerMode: "file" | "issue";
+}): IssueValidationResult;
+export declare function validateIssueFromFile(filePath: string, config: HarnessConfig, intendedPhase?: IntendedPhase): Promise<IssueValidationResult>;
+export declare function validateIssueFromLinear(issueKey: string, config: HarnessConfig, linearApiKey: string, intendedPhase?: IntendedPhase): Promise<IssueValidationResult>;
+export declare function validateIssue(options: ValidateIssueOptions): Promise<IssueValidationResult>;
+export declare function resolveValidationExitCode(result: IssueValidationResult): number;
+//# sourceMappingURL=issue.d.ts.map

package/dist/validate/issue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue.d.ts","sourceRoot":"","sources":["../../src/validate/issue.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAYxD,OAAO,KAAK,EACV,aAAa,EACb,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAsGpB,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,EACpD,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE;IACP,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC;CACtC,GACA,qBAAqB,CA0EvB;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa,EACrB,aAAa,CAAC,EAAE,aAAa,GAC5B,OAAO,CAAC,qBAAqB,CAAC,CAahC;AAED,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,MAAM,EACpB,aAAa,CAAC,EAAE,aAAa,GAC5B,OAAO,CAAC,qBAAqB,CAAC,CAsBhC;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,qBAAqB,CAAC,CAqBhC;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,qBAAqB,GAC5B,MAAM,CAKR"}

package/dist/validate/issue.js

@@ -0,0 +1,177 @@
+import { readFile } from "node:fs/promises";
+import { loadHarnessConfig } from "../config/load-config.js";
+import { parseFixtureMarkdown } from "../fixture/frontmatter.js";
+import { fetchLinearIssue } from "../linear/client.js";
+import { parseIssueDescription } from "../linear/parser.js";
+import { findLatestPlanningComment } from "../linear/planning-comment.js";
+import { createLinearClient, listIssueComments } from "../linear/writer.js";
+import { ResolverError } from "../resolver/errors.js";
+import { resolveTargetRepo } from "../resolver/target-repo.js";
+import { getNarrowFailureReason, isNarrowImplementationIssue, } from "../runner/idempotency.js";
+function buildRepairInstructions(result, intendedPhase) {
+    const repairs = [];
+    if (result.parseErrors.length > 0) {
+        repairs.push("Fix parser errors: add required ## sections (Task, Acceptance criteria, Out of scope) with hyphen bullets for criteria and out-of-scope items.");
+        for (const error of result.parseErrors) {
+            repairs.push(`- ${error}`);
+        }
+    }
+    if (result.resolverError) {
+        if (result.resolverError.classification === "missing_target_repo") {
+            repairs.push("Assign the issue to a mapped Linear project (see harness.config.json linearProjects) or add ## Target repo / Target repo: under ## Context and links.");
+        }
+        else if (result.resolverError.classification === "unknown_repo_denied") {
+            repairs.push("Use a repo listed in harness.config.json allowedTargetRepos, or add the repo to the allowlist.");
+        }
+        else {
+            repairs.push(result.resolverError.message);
+        }
+    }
+    if (result.validForPlanning &&
+        !result.validForDirectImplementation &&
+        intendedPhase === "implementation") {
+        if (!result.narrowIssue && !result.hasPlanningMarker) {
+            repairs.push("Too broad for Ready for Build — narrow task/AC, set recommended status to Ready for Planning, or complete a planning run first.");
+            if (result.narrowFailureReason) {
+                repairs.push(`Narrow heuristic: ${result.narrowFailureReason}`);
+            }
+            if (result.planningMarkerMode === "file") {
+                repairs.push("File validation cannot see Linear planning markers; re-validate with --issue after planning completes.");
+            }
+        }
+    }
+    if (!result.validForPlanning && intendedPhase === "planning") {
+        repairs.push("Issue is not ready for Ready for Planning — resolve parser and target repo errors first.");
+    }
+    return repairs;
+}
+function buildRoutingNotes(validForPlanning, validForDirectImplementation, narrowIssue, hasPlanningMarker, intendedPhase, resolutionSource) {
+    const notes = [];
+    if (resolutionSource === "project") {
+        notes.push("Target repo derived from Linear project mapping.");
+    }
+    else if (resolutionSource === "team") {
+        notes.push("Target repo derived from Linear team mapping.");
+    }
+    if (validForPlanning) {
+        notes.push("Set Linear status to Ready for Planning to run the planning phase.");
+    }
+    if (validForDirectImplementation) {
+        notes.push("Set Linear status to Ready for Build to run direct implementation.");
+    }
+    else if (validForPlanning && !narrowIssue && !hasPlanningMarker) {
+        notes.push("Issue is planning-valid but too broad for build-direct without a planning marker.");
+    }
+    if (hasPlanningMarker) {
+        notes.push("Durable planning comment found — broad issues may proceed to implementation.");
+    }
+    if (intendedPhase === "implementation" && validForPlanning && !validForDirectImplementation) {
+        notes.push("Recommended status should be Ready for Planning, not Ready for Build.");
+    }
+    return notes;
+}
+export function computeIssueValidation(description, context, config, options) {
+    const intendedPhase = options.intendedPhase ?? null;
+    const hasPlanningMarker = options.hasPlanningMarker ?? false;
+    const parsed = parseIssueDescription(description);
+    const parseErrors = [...parsed.parseErrors];
+    let targetRepo = null;
+    let resolutionSource = null;
+    let resolverError = null;
+    if (parseErrors.length === 0) {
+        try {
+            const resolved = resolveTargetRepo(parsed, context, config);
+            targetRepo = resolved.targetRepo;
+            resolutionSource = resolved.resolutionSource;
+        }
+        catch (error) {
+            if (error instanceof ResolverError) {
+                resolverError = {
+                    classification: error.classification,
+                    message: error.message,
+                };
+            }
+            else {
+                resolverError = {
+                    classification: "ambiguous_issue",
+                    message: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }
+    }
+    const validForPlanning = parseErrors.length === 0 && resolverError === null;
+    const narrowIssue = isNarrowImplementationIssue(parsed);
+    const narrowFailureReason = getNarrowFailureReason(parsed);
+    const validForDirectImplementation = validForPlanning && (narrowIssue || hasPlanningMarker);
+    const routingNotes = buildRoutingNotes(validForPlanning, validForDirectImplementation, narrowIssue, hasPlanningMarker, intendedPhase, resolutionSource);
+    const base = {
+        validForPlanning,
+        validForDirectImplementation,
+        targetRepo,
+        resolutionSource,
+        parseErrors,
+        resolverError,
+        narrowIssue,
+        narrowFailureReason,
+        hasPlanningMarker,
+        planningMarkerMode: options.planningMarkerMode,
+        routingNotes,
+    };
+    const repairInstructions = buildRepairInstructions(base, intendedPhase);
+    let passesIntendedPhase = null;
+    if (intendedPhase === "planning") {
+        passesIntendedPhase = validForPlanning;
+    }
+    else if (intendedPhase === "implementation") {
+        passesIntendedPhase = validForDirectImplementation;
+    }
+    return {
+        ...base,
+        intendedPhase,
+        passesIntendedPhase,
+        repairInstructions,
+    };
+}
+export async function validateIssueFromFile(filePath, config, intendedPhase) {
+    const raw = await readFile(filePath, "utf8");
+    const { metadata, body } = parseFixtureMarkdown(raw);
+    return computeIssueValidation(body, {
+        projectName: metadata.projectName ?? undefined,
+        teamName: metadata.teamName ?? undefined,
+    }, config, { intendedPhase, hasPlanningMarker: false, planningMarkerMode: "file" });
+}
+export async function validateIssueFromLinear(issueKey, config, linearApiKey, intendedPhase) {
+    const issue = await fetchLinearIssue(issueKey, linearApiKey);
+    const client = createLinearClient(linearApiKey);
+    const comments = await listIssueComments(client, issue.id);
+    const planningComment = findLatestPlanningComment(comments, config.orchestratorMarker);
+    return computeIssueValidation(issue.description ?? "", {
+        projectName: issue.projectName ?? undefined,
+        teamName: issue.teamName ?? undefined,
+    }, config, {
+        intendedPhase,
+        hasPlanningMarker: planningComment !== null,
+        planningMarkerMode: "issue",
+    });
+}
+export async function validateIssue(options) {
+    const { config } = await loadHarnessConfig({ configPath: options.configPath });
+    if (options.filePath) {
+        return validateIssueFromFile(options.filePath, config, options.intendedPhase);
+    }
+    if (options.issueKey) {
+        const apiKey = options.linearApiKey ?? process.env.LINEAR_API_KEY ?? "";
+        if (!apiKey) {
+            throw new Error("LINEAR_API_KEY is required for --issue validation");
+        }
+        return validateIssueFromLinear(options.issueKey, config, apiKey, options.intendedPhase);
+    }
+    throw new Error("Either filePath or issueKey is required");
+}
+export function resolveValidationExitCode(result) {
+    if (result.intendedPhase === "implementation") {
+        return result.validForDirectImplementation ? 0 : 2;
+    }
+    return result.validForPlanning ? 0 : 2;
+}
+//# sourceMappingURL=issue.js.map

package/dist/validate/issue.js.map

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

package/dist/validate/report.d.ts

@@ -0,0 +1,3 @@
+import type { IssueValidationResult } from "./types.js";
+export declare function formatValidationReport(result: IssueValidationResult): string;
+//# sourceMappingURL=report.d.ts.map