@surlymochan/evalid 0.0.0-stage → 0.4.1

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "@surlymochan/evalid",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.1",
+  "description": "Claimed != verified: a runtime verification layer for coding agents. It seals each test run and replays it from a clean snapshot, with a zero-judge gate pipeline (spec clarification, code review, TDD proof) and the xflow CLI.",
+  "keywords": [
+    "ai-agents",
+    "coding-agents",
+    "workflow",
+    "tdd",
+    "cli",
+    "codex",
+    "claude-code",
+    "cursor",
+    "openspec",
+    "developer-tools"
+  ],
+  "homepage": "https://github.com/surlymochan/evalid#readme",
+  "bugs": {
+    "url": "https://github.com/surlymochan/evalid/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/surlymochan/evalid.git"
+  },
+  "author": "Chao Chen (https://github.com/surlymochan)",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "xflow": "bin/xflow.js"
+  },
+  "files": [
+    "README.md",
+    "RELEASE_NOTES.md",
+    "CHANGELOG.md",
+    "atoms/",
+    "bin/",
+    "docs/",
+    "!docs/adoption/evidence/**",
+    "!docs/adoption/trial-packets/**",
+    "!docs/benchmark-evidence/**",
+    "!docs/assets/**",
+    "prompts/",
+    "schemas/",
+    "scripts/",
+    "specs/README.md",
+    "specs/architecture.md",
+    "specs/product.md",
+    "specs/workflow.md",
+    "src/",
+    "workflows/",
+    "xflow/",
+    "!**/__pycache__/**",
+    "!**/*.pyc"
+  ],
+  "engines": {
+    "node": ">=22.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node bin/xflow.js serve",
+    "test": "node scripts/run-tests.mjs",
+    "drift:scan": "node --test test/workflow-drift-scan.test.js",
+    "doctor": "node bin/xflow.js doctor",
+    "verify": "npm test",
+    "skill:sync": "sh xflow/scripts/sync_installed_xflow_skill.sh",
+    "skill:diff": "sh xflow/scripts/check_installed_xflow_skill_sync.sh",
+    "pack:check": "npm pack --dry-run",
+    "publish:check": "npm run release:pack && npm publish --dry-run --access public",
+    "release:local": "npm run verify && npm run drift:scan && npm run skill:sync && npm run skill:diff",
+    "release:pack": "npm run verify && npm run drift:scan && npm run skill:diff && npm run pack:check",
+    "workflow:yolo": "node bin/xflow.js workflow run workflows/yolo.yaml",
+    "workflow:corps": "node bin/xflow.js corps",
+    "atom:list": "node bin/xflow.js atom list"
+  },
+  "dependencies": {
+    "ajv": "^8.12.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "playwright": "^1.59.1"
+  }
+}

package/prompts/pencil-draft.md

@@ -0,0 +1,46 @@
+# Pencil Draft — {{phase_label}}
+
+## Mission
+Turn the already-selected design direction and winning layout into a single concrete Pencil draft.
+
+## Context
+- **Change ID**: {{change_id}}
+- **Artifact Directory**: {{artifact_dir}}
+- **Primary Output**: `{{expected_artifact}}`
+
+## Required Upstream Inputs
+Before drawing, read these files when they exist in `{{artifact_dir}}`:
+1. `design_contract.json`
+2. `competitor_reconstruction_review.json`
+3. `reference_surface_lock.json`
+4. `reconstruction_pack.json`
+5. `generation_contract.json`
+6. `design_system_pack.json`
+7. `image_reference_set.json`
+8. `visual_direction_synthesis.json`
+9. `layout_competition.json`
+10. `design_selection.json`
+11. `ux_design_brief.json`
+12. `pencil_generation_plan.json` (when already prepared)
+
+## Execution Rules
+1. Build exactly one winning desktop/product surface, not multiple alternatives.
+2. Follow the selected direction, winning layout, generation contract, and UX brief literally when they are present.
+3. Generate in stages: shell first, then primary focus components, then supporting components, then local polish.
+4. Treat `component_blueprint` and `staged_generation` as execution instructions, not optional context.
+5. Keep the composition product-like and implementation-ready; avoid decorative exploration loops.
+6. Prefer one primary frame/workbench with the key panels, controls, and hierarchy already laid out.
+7. Treat the primary reference surface lock as the source of truth; supporting surfaces may only refine, not replace, the locked skeleton.
+8. Keep naming and structure readable for downstream refinement and benchmark comparison.
+9. Treat `visual_constraints.aesthetic_standard` as a hard quality bar, not a mood-board suggestion.
+10. When `visual_constraints.image_reference_generation` is enabled, read `image_reference_set.json` and use its materialized GPT/image-model reference artifacts as high-aesthetic targets, then translate them into editable Pencil primitives; do not ship bitmap mockups as the implementation.
+11. Read `design_system_pack.json` as a hard design-system contract: allowed primitives, required states, token policy, preview loop, and commercial/open practice sources must shape the draft.
+12. Pencil is the editable assembly/refinement surface. It is not sufficient by itself for high-aesthetic UI unless the design-system pack, image-reference, and benchmark evidence also converge.
+
+## Output
+- Save the Pencil file to: `{{expected_artifact}}`
+- Also write any required supporting outputs:
+{{auxiliary_outputs}}
+
+## Stop Condition
+Finish when the draft clearly reflects the frozen direction/layout and is ready for review or refinement.

package/prompts/pencil-refine.md

@@ -0,0 +1,46 @@
+# Pencil Refine — {{phase_label}}
+
+## Mission
+Refine the existing Pencil draft using the latest review and benchmark evidence, without reopening the design direction.
+
+## Context
+- **Change ID**: {{change_id}}
+- **Artifact Directory**: {{artifact_dir}}
+- **Primary Output**: `{{expected_artifact}}`
+
+## Required Inputs
+Read these files when they exist in `{{artifact_dir}}`:
+1. `pencil_output.pen`
+2. `llm_design_review.json`
+3. `visual_benchmark.json`
+4. `benchmark_repair_plan.json`
+5. `generation_contract.json`
+6. `design_system_pack.json`
+7. `image_reference_set.json`
+8. `design_selection.json`
+9. `ux_design_brief.json`
+10. `pencil_refine_targets.json` (when already prepared)
+
+## Execution Rules
+0. Fast path: if `benchmark_repair_plan.json` says `status: "not_needed"` and `visual_benchmark.json` shows every scenario passing, preserve the existing draft, do not inspect or rewrite component internals, and save the current Pencil file to the primary output as an explicit no-op refinement.
+1. Start from the existing Pencil draft instead of recreating the surface from scratch.
+2. Apply only the changes needed to address review findings, benchmark deltas, repair-plan hotspots, and hierarchy issues.
+3. Treat each repair target as component-local work; preserve non-target components unless a target explicitly includes them.
+4. Respect refine scopes from `pencil_refine_targets.json` when present:
+   - `allow_big_change`: geometry, hierarchy, and local structure may change inside the target bounds.
+   - `micro_tune_only`: only tokens, spacing, copy rhythm, and small alignment nudges may change.
+   - `freeze`: do not visually or structurally alter these components in this pass.
+5. Preserve the selected layout and product logic unless the review evidence clearly requires adjustment.
+6. Use the generation contract and locked primary reference surface to keep refinement convergent.
+7. Keep refinement focused and convergent; avoid opening new stylistic branches or whole-page redraws.
+8. Preserve the high-aesthetic contract from `generation_contract.json`; fixes that improve similarity but damage hierarchy, typography rhythm, density, or interaction polish are regressions.
+9. If `image_reference_set.json` is present, refine toward its material quality and component rhythm while keeping the product surface editable and benchmarkable.
+10. Keep refinements inside `design_system_pack.json`: do not invent primitives, omit required states, or bypass the preview/proof loop to make a local visual fix easier.
+
+## Output
+- Save the refined Pencil file to: `{{expected_artifact}}`
+- Also write any required supporting outputs:
+{{auxiliary_outputs}}
+
+## Stop Condition
+Finish when the draft is materially improved against the review evidence and ready for design acceptance.

package/prompts/phase-artifact.md

@@ -0,0 +1,24 @@
+# Heavy Phase — {{phase_label}}
+
+## Context
+- **Change ID**: {{change_id}}
+- **Phase**: {{phase_id}} ({{phase_label}})
+- **Artifact Directory**: {{artifact_dir}}
+
+## Intake
+{{intake}}
+
+## Task
+Produce the primary artifact for this phase and any required supporting outputs.
+
+### Primary Output
+Write the primary artifact to: `{{expected_artifact}}`
+
+### Supporting Outputs
+{{auxiliary_outputs}}
+
+### Requirements
+1. Read any existing proposal, plan, design, or prior phase artifacts in `{{artifact_dir}}`
+2. Perform the work required for this phase instead of writing placeholder prose
+3. Keep outputs consistent with the current phase semantics and downstream gates
+4. If code or design artifacts must change, update the project checkout directly

package/prompts/phase-execution.md

@@ -0,0 +1,32 @@
+# Execution Phase — {{phase_label}}
+
+## Context
+- **Change ID**: {{change_id}}
+- **Phase**: {{phase_id}} ({{phase_label}})
+- **Artifact Directory**: {{artifact_dir}}
+
+## Intake
+{{intake}}
+
+## Task
+Produce the real artifact for this phase and any necessary supporting changes.
+
+## Phase Guidance
+{{phase_guidance}}
+
+### Requirements
+1. Read any existing plan, proposal, or spec files in {{artifact_dir}}
+2. Perform the actual work required for this phase according to the frozen scope
+3. Write the primary phase artifact to `{{expected_artifact}}`
+4. Ensure the artifact is concrete and downstream-gate ready, not placeholder prose
+5. If code or design artifacts must change, update the project checkout directly
+
+### Artifact Expectations
+The primary artifact should contain phase-appropriate structured evidence such as:
+   - `phase_id`: "{{phase_id}}"
+   - `summary`: "What was implemented"
+   - `files_changed`: ["list", "of", "files"]
+   - `verification`: "commands run and results"
+
+### Output
+Write the primary artifact to: `{{expected_artifact}}`

package/schemas/competitor-reconstruction-contract.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openflow/schemas/competitor-reconstruction-contract.schema.json",
+  "title": "Competitor Reconstruction Contract",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status",
+    "competitor_product",
+    "target_surfaces",
+    "primary_reference_surface",
+    "supporting_reference_surfaces",
+    "required_modules",
+    "primary_journeys",
+    "business_logic_invariants",
+    "decomposition_requirements"
+  ],
+  "properties": {
+    "status": {
+      "type": "string",
+      "const": "frozen"
+    },
+    "competitor_product": {
+      "type": "string",
+      "minLength": 1
+    },
+    "target_surfaces": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "primary_reference_surface": {
+      "type": "string",
+      "minLength": 1
+    },
+    "supporting_reference_surfaces": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "required_modules": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "primary_journeys": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "business_logic_invariants": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "decomposition_requirements": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "surface_map_required",
+        "layout_map_required",
+        "component_inventory_required",
+        "state_inventory_required",
+        "visual_token_map_required",
+        "reference_intermediate_model_required"
+      ],
+      "properties": {
+        "surface_map_required": { "type": "boolean" },
+        "layout_map_required": { "type": "boolean" },
+        "component_inventory_required": { "type": "boolean" },
+        "state_inventory_required": { "type": "boolean" },
+        "visual_token_map_required": { "type": "boolean" },
+        "reference_intermediate_model_required": { "type": "boolean" }
+      }
+    }
+  }
+}

package/schemas/llm-design-review-aggregate.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openflow/schemas/llm-design-review-aggregate.schema.json",
+  "title": "LLM Design Review Aggregate",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "version",
+    "phase",
+    "summary",
+    "benchmark_summary",
+    "worker_runs",
+    "aggregated_at"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "phase": {
+      "type": "string",
+      "const": "llm_design_review"
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "benchmark_summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "scenario_count",
+        "passed_count",
+        "needs_follow_up_count",
+        "statuses"
+      ],
+      "properties": {
+        "scenario_count": { "type": "integer", "minimum": 0 },
+        "passed_count": { "type": "integer", "minimum": 0 },
+        "needs_follow_up_count": { "type": "integer", "minimum": 0 },
+        "statuses": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "status"],
+            "properties": {
+              "id": { "type": ["string", "null"] },
+              "status": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "worker_runs": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["visual_review", "visual_benchmark"],
+      "properties": {
+        "visual_review": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["artifact_file"],
+          "properties": {
+            "artifact_file": { "type": "string", "minLength": 1 }
+          }
+        },
+        "visual_benchmark": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["artifact_file"],
+          "properties": {
+            "artifact_file": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    },
+    "aggregated_at": {
+      "type": "string",
+      "minLength": 1
+    }
+  }
+}