p-dev-harness 0.3.0 → 0.4.0

package/workspace-snapshot/files/src/workflow-page/fixtures/model-catalog-snapshot.ts

@@ -0,0 +1,34 @@
+import type { WorkflowModelCatalogEntry } from "../types.js";
+
+/**
+ * Verified Cursor.models.list() capture was not available in this implementation
+ * environment (no CURSOR_API_KEY). Fixture mode uses this deterministic snapshot
+ * with the models confirmed in prior fixture seeds only.
+ */
+export const FIXTURE_MODEL_CATALOG_CAPTURED_AT = "2026-01-01T00:00:00.000Z";
+
+export const FIXTURE_MODEL_CATALOG_LIMITATION =
+  "Multi-model fixture catalog requires a verified Cursor.models.list() capture. Only models from existing fixture seeds are included until capture is available.";
+
+export function getFixtureModelCatalog(): WorkflowModelCatalogEntry[] {
+  return FIXTURE_MODEL_CATALOG.map((entry) => ({ ...entry }));
+}
+
+const FIXTURE_MODEL_CATALOG: WorkflowModelCatalogEntry[] = [
+  {
+    id: "composer-2.5",
+    displayName: "Composer 2.5",
+    availability: "available",
+    supportedParameters: [
+      {
+        id: "fast",
+        label: "Fast mode",
+        type: "boolean",
+        allowedValues: ["true", "false"],
+        defaultValue: "true",
+      },
+    ],
+    fetchedAt: FIXTURE_MODEL_CATALOG_CAPTURED_AT,
+    source: "fixture",
+  },
+];

package/workspace-snapshot/files/src/workflow-page/fixtures/workflow-scopes.ts

@@ -0,0 +1,18 @@
+import type { WorkflowScope } from "../types.js";
+
+export const FIXTURE_WORKFLOW_SCOPES: WorkflowScope[] = [
+  {
+    id: "target-app",
+    targetRepo: "weston-uribe/example-target-app",
+    linearTeams: ["Product Development"],
+  },
+  {
+    id: "harness-repo",
+    targetRepo: "weston-uribe/agentic-product-development-harness",
+    linearTeams: ["Harness"],
+  },
+];
+
+export function getFixtureWorkflowScopes(): WorkflowScope[] {
+  return FIXTURE_WORKFLOW_SCOPES.map((scope) => ({ ...scope }));
+}

package/workspace-snapshot/files/src/workflow-page/linear-status-source.ts

@@ -0,0 +1,65 @@
+import {
+  createLinearSetupClient,
+  listTeamWorkflowStates,
+} from "../setup/linear-setup-client.js";
+import type { LinearStatusInput } from "./current-workflow.js";
+import type { CatalogLoadState } from "./types.js";
+import { hashWorkflowFingerprint } from "./fingerprint.js";
+
+export interface LinearStatusLoadResult {
+  statuses: LinearStatusInput[];
+  loadState: CatalogLoadState;
+  warning?: string;
+  error?: string;
+}
+
+export async function loadLiveLinearStatuses(input: {
+  apiKey: string;
+  teamId: string;
+}): Promise<LinearStatusLoadResult> {
+  try {
+    const client = createLinearSetupClient(input.apiKey);
+    const states = await listTeamWorkflowStates(client, input.teamId);
+    return {
+      statuses: states.map((state) => ({
+        id: state.id,
+        name: state.name,
+        type: state.type,
+      })),
+      loadState: "loaded",
+    };
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message : "Linear status load failed.";
+    return {
+      statuses: [],
+      loadState: "unavailable",
+      error: message,
+    };
+  }
+}
+
+export function buildStatusCatalogFingerprint(
+  statuses: LinearStatusInput[],
+): string {
+  return hashWorkflowFingerprint(
+    statuses
+      .map((status) => ({
+        id: status.id,
+        name: status.name,
+        type: status.type,
+      }))
+      .sort((left, right) => left.id.localeCompare(right.id)),
+  );
+}
+
+export function sanitizeLinearColor(color: unknown): string | undefined {
+  if (typeof color !== "string") {
+    return undefined;
+  }
+  const trimmed = color.trim();
+  if (/^#[0-9a-fA-F]{3,8}$/.test(trimmed)) {
+    return trimmed;
+  }
+  return undefined;
+}

package/workspace-snapshot/files/src/workflow-page/model-catalog-lookup.ts

@@ -0,0 +1,8 @@
+import type { WorkflowModelCatalogEntry } from "./types.js";
+
+export function lookupModelInCatalog(
+  catalog: WorkflowModelCatalogEntry[],
+  modelId: string,
+): WorkflowModelCatalogEntry | undefined {
+  return catalog.find((entry) => entry.id === modelId);
+}

package/workspace-snapshot/files/src/workflow-page/model-catalog-utils.ts

@@ -0,0 +1,83 @@
+import type {
+  WorkflowModelCatalogEntry,
+  WorkflowModelParameterDefinition,
+} from "./types.js";
+import { hashWorkflowFingerprint } from "./fingerprint.js";
+
+interface RawCursorModel {
+  id: string;
+  name?: string;
+  displayName?: string;
+  parameters?: Array<{
+    id: string;
+    name?: string;
+    label?: string;
+    type?: string;
+    allowedValues?: string[];
+    defaultValue?: string;
+  }>;
+}
+
+function normalizeParameter(
+  parameter: NonNullable<RawCursorModel["parameters"]>[number],
+): WorkflowModelParameterDefinition {
+  const type =
+    parameter.type === "boolean" ||
+    parameter.type === "enum" ||
+    parameter.type === "string"
+      ? parameter.type
+      : parameter.allowedValues && parameter.allowedValues.length > 0
+        ? "enum"
+        : "string";
+
+  return {
+    id: parameter.id,
+    label: parameter.label ?? parameter.name ?? parameter.id,
+    type,
+    allowedValues: parameter.allowedValues,
+    defaultValue: parameter.defaultValue,
+  };
+}
+
+export function normalizeCursorModelCatalog(
+  models: RawCursorModel[],
+  source: "cursor-live" | "fixture",
+  fetchedAt: string,
+): WorkflowModelCatalogEntry[] {
+  return models.map((model) => ({
+    id: model.id,
+    displayName: model.displayName ?? model.name ?? model.id,
+    availability: "available" as const,
+    supportedParameters: (model.parameters ?? []).map(normalizeParameter),
+    fetchedAt,
+    source,
+  }));
+}
+
+export function buildCatalogUnavailableEntry(
+  source: "cursor-live" | "fixture",
+): WorkflowModelCatalogEntry[] {
+  return [
+    {
+      id: "catalog-unavailable",
+      displayName: "Model catalog unavailable",
+      availability: "catalog-unavailable",
+      supportedParameters: [],
+      source,
+    },
+  ];
+}
+
+export function buildModelCatalogFingerprint(
+  catalog: WorkflowModelCatalogEntry[],
+): string {
+  return hashWorkflowFingerprint(
+    catalog.map((entry) => ({
+      id: entry.id,
+      availability: entry.availability,
+      parameters: entry.supportedParameters.map((parameter) => parameter.id),
+    })),
+  );
+}
+
+export type { RawCursorModel };

package/workspace-snapshot/files/src/workflow-page/model-catalog.ts

@@ -0,0 +1,60 @@
+import type { HarnessConfig } from "../config/types.js";
+import type { CatalogLoadState, WorkflowModelCatalogEntry } from "./types.js";
+import {
+  buildCatalogUnavailableEntry,
+  normalizeCursorModelCatalog,
+  type RawCursorModel,
+} from "./model-catalog-utils.js";
+
+export {
+  buildCatalogUnavailableEntry,
+  buildModelCatalogFingerprint,
+  normalizeCursorModelCatalog,
+} from "./model-catalog-utils.js";
+export { lookupModelInCatalog } from "./model-catalog-lookup.js";
+
+export const WORKFLOW_MODEL_POLICY_NOTE =
+  "Planner and builder model selections are saved to harness.config.json roleModels and affect runtime agents.";
+
+export interface ModelCatalogLoadResult {
+  catalog: WorkflowModelCatalogEntry[];
+  loadState: CatalogLoadState;
+}
+
+export async function fetchLiveCursorModelCatalog(
+  apiKey: string,
+): Promise<ModelCatalogLoadResult> {
+  const fetchedAt = new Date().toISOString();
+  try {
+    const { Cursor } = await import("@cursor/sdk");
+    const models = (await Cursor.models.list({
+      apiKey: apiKey.trim(),
+    })) as RawCursorModel[];
+    return {
+      catalog: normalizeCursorModelCatalog(models, "cursor-live", fetchedAt),
+      loadState: "loaded",
+    };
+  } catch {
+    return {
+      catalog: buildCatalogUnavailableEntry("cursor-live"),
+      loadState: "unavailable",
+    };
+  }
+}
+
+export function emptyHarnessConfig(): HarnessConfig {
+  return {
+    version: 1,
+    orchestratorMarker: "harness-orchestrator-v1",
+    logDirectory: "runs",
+    repos: [
+      {
+        id: "target-app",
+        targetRepo: "https://github.com/weston-uribe/example-target-app",
+        baseBranch: "main",
+        productionBranch: "main",
+      },
+    ],
+    allowedTargetRepos: ["https://github.com/weston-uribe/example-target-app"],
+  };
+}

package/workspace-snapshot/files/src/workflow-page/scope-branches.ts

@@ -0,0 +1,27 @@
+import type { HarnessConfig } from "../config/types.js";
+import type { WorkflowScope } from "./types.js";
+
+export function resolveScopeBranchRelationship(input: {
+  scope: WorkflowScope;
+  config?: HarnessConfig;
+}): { baseBranch: string; productionBranch: string } {
+  const repoMapping = input.config?.repos.find((repo) => repo.id === input.scope.id);
+  return {
+    baseBranch: repoMapping?.baseBranch ?? "main",
+    productionBranch: repoMapping?.productionBranch ?? "main",
+  };
+}
+
+export function enrichWorkflowScopes(
+  scopes: WorkflowScope[],
+  config?: HarnessConfig,
+): WorkflowScope[] {
+  return scopes.map((scope) => {
+    const branches = resolveScopeBranchRelationship({ scope, config });
+    return {
+      ...scope,
+      baseBranch: branches.baseBranch,
+      productionBranch: branches.productionBranch,
+    };
+  });
+}

package/workspace-snapshot/files/src/workflow-page/source-context.ts

@@ -0,0 +1,91 @@
+import {
+  isWorkflowFixtureId,
+  P_DEV_OPERATIONS_FIXTURES_ENV,
+  P_DEV_WORKFLOW_FIXTURES_ENV,
+} from "./constants.js";
+import type { WorkflowSourceContext, WorkflowSourceMode } from "./types.js";
+
+export interface SourceContextRequest {
+  source?: string | null;
+  fixture?: string | null;
+  scope?: string | null;
+  fixturesEnabled?: boolean;
+}
+
+export function isFixturesOptInEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return (
+    env[P_DEV_WORKFLOW_FIXTURES_ENV] === "1" ||
+    env[P_DEV_OPERATIONS_FIXTURES_ENV] === "1"
+  );
+}
+
+export function resolveWorkflowSourceContext(
+  request: SourceContextRequest,
+  env: NodeJS.ProcessEnv = process.env,
+): WorkflowSourceContext {
+  const fixturesEnabled = request.fixturesEnabled ?? isFixturesOptInEnabled(env);
+  const source = request.source?.trim().toLowerCase();
+  const fixture = request.fixture?.trim();
+  const scope = request.scope?.trim();
+
+  if (source === "fixture" || fixture) {
+    if (!fixturesEnabled) {
+      return {
+        mode: "fixture",
+        fixtureId: fixture,
+        fixturesEnabled: false,
+        rejectionReason:
+          "Fixture mode requires explicit server opt-in via P_DEV_WORKFLOW_FIXTURES=1 or P_DEV_OPERATIONS_FIXTURES=1.",
+      };
+    }
+
+    if (!fixture || !isWorkflowFixtureId(fixture)) {
+      return {
+        mode: "fixture",
+        fixtureId: fixture,
+        fixturesEnabled: true,
+        rejectionReason: fixture
+          ? `Unknown fixture id: ${fixture}`
+          : "Fixture id is required when source=fixture.",
+      };
+    }
+
+    return {
+      mode: "fixture",
+      fixtureId: fixture,
+      scopeId: scope,
+      fixturesEnabled: true,
+    };
+  }
+
+  return {
+    mode: "live",
+    scopeId: scope,
+    fixturesEnabled,
+  };
+}
+
+export function dataSourceLabel(context: WorkflowSourceContext): string {
+  if (context.rejectionReason) {
+    return "Unavailable";
+  }
+  if (context.mode === "fixture") {
+    return "Browser test fixture";
+  }
+  return "Live harness configuration";
+}
+
+export function assertWritableSourceContext(
+  context: WorkflowSourceContext,
+): WorkflowSourceContext {
+  if (context.rejectionReason) {
+    throw new Error(context.rejectionReason);
+  }
+  return context;
+}
+
+export function sourceModeFromContext(
+  context: WorkflowSourceContext,
+): WorkflowSourceMode {
+  return context.mode;
+}

package/workspace-snapshot/files/src/workflow-page/types.ts

@@ -0,0 +1,134 @@
+import type {
+  CanonicalStatusKey,
+} from "../workflow/canonical-product-development-workflow.js";
+import type { RequiredWorkflowStatus } from "../setup/linear-status-contract.js";
+import type { CanonicalValidationViolation } from "../workflow/canonical-workflow-validation.js";
+import type { RoleModelRole } from "../config/role-models.js";
+
+export type WorkflowSourceMode = "live" | "fixture";
+
+export type WorkflowHealthState =
+  | "healthy"
+  | "blocking-configuration-error"
+  | "linear-unavailable";
+
+export interface WorkflowStatusRecord {
+  id: string;
+  name: string;
+  category: string;
+  color?: string;
+  source: "linear-live" | "fixture";
+  requiredWorkflowRole?: RequiredWorkflowStatus["role"];
+  participatesInCurrentHarnessWorkflow: boolean;
+  automationTriggerStatus: boolean;
+  currentMappingKeys: string[];
+  mappingState: "resolved" | "ambiguous" | "missing" | "unmapped";
+  canonicalStatusKey?: CanonicalStatusKey;
+}
+
+export interface WorkflowModelParameterDefinition {
+  id: string;
+  label: string;
+  type: "boolean" | "string" | "enum";
+  allowedValues?: string[];
+  defaultValue?: string;
+}
+
+export interface WorkflowModelCatalogEntry {
+  id: string;
+  displayName: string;
+  availability: "available" | "missing" | "catalog-unavailable";
+  supportedParameters: WorkflowModelParameterDefinition[];
+  fetchedAt?: string;
+  source: "cursor-live" | "fixture";
+}
+
+export type WorkflowModelSelectionSource =
+  | "roleModels"
+  | "agentProvider.model.id"
+  | "defaultModel.id"
+  | "code-default";
+
+export interface WorkflowModelSelection {
+  modelId: string;
+  displayName: string;
+  parameters: Array<{ id: string; value: string }>;
+  source: WorkflowModelSelectionSource;
+}
+
+export interface WorkflowCurrentWorkflowMapping {
+  mappingKey: string;
+  configuredStatusName: string;
+  resolvedStatusIds: string[];
+  state: "resolved" | "ambiguous" | "missing";
+}
+
+export interface WorkflowScope {
+  id: string;
+  targetRepo: string;
+  baseBranch?: string;
+  productionBranch?: string;
+  linearTeams?: string[];
+  linearProjects?: string[];
+}
+
+export type CatalogLoadState = "loaded" | "unavailable";
+
+export interface WorkflowCatalogLoadMetadata {
+  statusCatalog: CatalogLoadState;
+  modelCatalog: CatalogLoadState;
+}
+
+export interface WorkflowSourceContext {
+  mode: WorkflowSourceMode;
+  fixtureId?: string;
+  scopeId?: string;
+  fixturesEnabled: boolean;
+  rejectionReason?: string;
+}
+
+export interface WorkflowCanonicalWorkflowView {
+  healthState: WorkflowHealthState;
+  violations: CanonicalValidationViolation[];
+  informationalWarnings: import("../workflow/canonical-workflow-validation.js").CanonicalInformationalWarning[];
+  resolvedStatusIds: Partial<Record<CanonicalStatusKey, string>>;
+  mergePathVariant: "integration-then-production" | "direct-production";
+}
+
+export type ModelSaveReadinessState =
+  | "ready"
+  | "catalog-unavailable"
+  | "invalid-model"
+  | "invalid-parameter";
+
+export interface WorkflowRoleModelSaveReadiness {
+  role: RoleModelRole;
+  ready: boolean;
+  state: ModelSaveReadinessState;
+  issues: string[];
+}
+
+export interface ModelSaveReadiness {
+  planner: WorkflowRoleModelSaveReadiness;
+  builder: WorkflowRoleModelSaveReadiness;
+  ready: boolean;
+}
+
+export interface WorkflowBootstrapPayload {
+  sourceMode: WorkflowSourceMode;
+  fixtureId?: string;
+  selectedScopeId?: string;
+  scopes: WorkflowScope[];
+  statuses: WorkflowStatusRecord[];
+  currentWorkflowMappings: WorkflowCurrentWorkflowMapping[];
+  modelCatalog: WorkflowModelCatalogEntry[];
+  catalogLoadMetadata: WorkflowCatalogLoadMetadata;
+  plannerSelection: WorkflowModelSelection;
+  builderSelection: WorkflowModelSelection;
+  configFingerprint: string;
+  modelSaveReadiness: ModelSaveReadiness;
+  canonicalWorkflow: WorkflowCanonicalWorkflowView;
+  warnings: string[];
+  debugEnabled?: boolean;
+  dataSourceLabel: string;
+}

package/workspace-snapshot/files/src/workflow-page/workflow-scopes.ts

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+import type { HarnessConfig } from "../config/types.js";
+import type { WorkflowScope } from "./types.js";
+
+const GITHUB_REPO_PATTERN =
+  /^https:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)\/?$/;
+
+export function parseOwnerRepoFromTargetUrl(targetRepo: string): string {
+  const match = targetRepo.match(GITHUB_REPO_PATTERN);
+  if (match?.[1]) {
+    return match[1];
+  }
+  return targetRepo;
+}
+
+/** Derive a filesystem-safe filename from a validated scope id. Never pass raw URLs or query values. */
+export function deriveSafeScopeFilename(validatedScopeId: string): string {
+  return createHash("sha256")
+    .update(validatedScopeId, "utf8")
+    .digest("hex")
+    .slice(0, 32);
+}
+
+export function buildLiveWorkflowScopes(config: HarnessConfig): WorkflowScope[] {
+  return config.repos.map((repo) => ({
+    id: repo.id,
+    targetRepo: parseOwnerRepoFromTargetUrl(repo.targetRepo),
+    linearTeams: repo.linearTeams?.length ? [...repo.linearTeams] : undefined,
+    linearProjects: repo.linearProjects?.length ? [...repo.linearProjects] : undefined,
+  }));
+}
+
+export function resolveScopeAllowlist(
+  scopes: WorkflowScope[],
+): Map<string, WorkflowScope> {
+  return new Map(scopes.map((scope) => [scope.id, scope]));
+}
+
+export function validateRequestedScopeId(
+  requestedScopeId: string | undefined | null,
+  allowlist: Map<string, WorkflowScope>,
+): { scope: WorkflowScope | undefined; error?: string } {
+  if (!requestedScopeId?.trim()) {
+    if (allowlist.size === 1) {
+      const only = [...allowlist.values()][0];
+      return { scope: only };
+    }
+    if (allowlist.size === 0) {
+      return { scope: undefined, error: "No workflow repository scopes are configured." };
+    }
+    const first = [...allowlist.values()][0];
+    return { scope: first };
+  }
+
+  const scope = allowlist.get(requestedScopeId.trim());
+  if (!scope) {
+    return {
+      scope: undefined,
+      error: `Unknown workflow scope: ${requestedScopeId.trim()}`,
+    };
+  }
+  return { scope };
+}
+
+export function scopeStorageKey(input: {
+  fixtureId?: string;
+  scopeId: string;
+}): string {
+  if (input.fixtureId) {
+    return `${input.fixtureId}::${input.scopeId}`;
+  }
+  return input.scopeId;
+}

package/workspace-snapshot/files/templates/eval-scorecard.md

@@ -0,0 +1,54 @@
+# Eval scorecard: [Issue title]
+
+<!-- Human-readable readiness rubric. v0.1: manual scoring; automation planned for v0.2+. -->
+
+## Run metadata
+
+| Field | Value |
+|-------|-------|
+| Issue | |
+| Target repo | |
+| Branch / PR | |
+| Agent / executor | Cursor (manual loop) |
+| Date | |
+
+## Scoring legend
+
+| Score | Meaning |
+|-------|---------|
+| **Pass** | Criterion fully met; evidence attached |
+| **Partial** | Mostly met; minor gaps documented |
+| **Fail** | Not met; blocks readiness |
+| **N/A** | Not applicable to this work type |
+
+## Criteria
+
+| # | Criterion | Score | Evidence |
+|---|-----------|-------|----------|
+| 1 | Matches acceptance criteria from issue | | |
+| 2 | Scope limited to approved plan | | |
+| 3 | No secrets or env files committed | | |
+| 4 | Lint / typecheck pass (if applicable) | | |
+| 5 | UI matches intent on desktop (if applicable) | | |
+| 6 | UI matches intent on mobile (if applicable) | | |
+| 7 | Copy / content reviewed for accuracy | | |
+| 8 | Accessibility basics (labels, contrast) if UI | | |
+
+Add or remove rows per issue. Document why rows are N/A.
+
+## Summary
+
+- **Overall readiness:** Ready / Not ready / Ready with notes
+- **Blocking failures:** (list criterion numbers or none)
+
+## Human sign-off
+
+- [ ] PM / owner reviewed scorecard
+- Sign-off: _______________
+- Date: _______________
+
+## Follow-ups
+
+Issues or template improvements discovered during this eval:
+
+-