@surlymochan/evalid 0.0.0-stage → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (192) hide show
  1. package/CHANGELOG.md +94 -0
  2. package/LICENSE +21 -0
  3. package/README.md +315 -2
  4. package/RELEASE_NOTES.md +124 -0
  5. package/atoms/registry.json +758 -0
  6. package/bin/xflow.js +7261 -0
  7. package/docs/adoption/README.md +128 -0
  8. package/docs/adoption/openflow-release-hardening.md +61 -0
  9. package/docs/benchmark-openflow-vs-gstack-superpowers-openspec-2026-05-25.md +81 -0
  10. package/docs/compatibility.md +52 -0
  11. package/docs/competitive-benchmark.md +108 -0
  12. package/docs/corps-operator-guide.md +75 -0
  13. package/docs/demo-proof.md +126 -0
  14. package/docs/examples-gallery.md +115 -0
  15. package/docs/fixtures/tracker-item.json +7 -0
  16. package/docs/goal-vs-codex.md +129 -0
  17. package/docs/gstack-comparison.md +88 -0
  18. package/docs/install-upgrade.md +133 -0
  19. package/docs/integrations.md +49 -0
  20. package/docs/launch-demo.md +123 -0
  21. package/docs/launch-dossier.md +180 -0
  22. package/docs/methodology.md +149 -0
  23. package/docs/npm-publish-handoff.md +96 -0
  24. package/docs/openspec-migration.md +106 -0
  25. package/docs/public-benchmark.md +68 -0
  26. package/docs/public-release.md +145 -0
  27. package/docs/quality-assessment.md +139 -0
  28. package/docs/quickstart.md +156 -0
  29. package/docs/reviewer-guide.md +43 -0
  30. package/docs/spec-kit-benchmark.md +73 -0
  31. package/docs/super-assistant-comparison.md +106 -0
  32. package/docs/superpowers-comparison.md +82 -0
  33. package/docs/team-adoption.md +123 -0
  34. package/docs/tooling-matrix.md +91 -0
  35. package/docs/walkthrough.md +76 -0
  36. package/docs/workflow-manual.md +1130 -0
  37. package/package.json +83 -4
  38. package/prompts/pencil-draft.md +46 -0
  39. package/prompts/pencil-refine.md +46 -0
  40. package/prompts/phase-artifact.md +24 -0
  41. package/prompts/phase-execution.md +32 -0
  42. package/schemas/competitor-reconstruction-contract.schema.json +91 -0
  43. package/schemas/llm-design-review-aggregate.schema.json +83 -0
  44. package/schemas/visual-benchmark.schema.json +978 -0
  45. package/schemas/workflow.schema.json +100 -0
  46. package/scripts/run-tests.mjs +23 -0
  47. package/scripts/takein_digest.py +139 -0
  48. package/specs/README.md +118 -0
  49. package/specs/architecture.md +36 -0
  50. package/specs/product.md +33 -0
  51. package/specs/workflow.md +349 -0
  52. package/src/agent_team/atoms/codex-app-bridge.js +8 -0
  53. package/src/agent_team/atoms/design/competitor-reconstruction-review.js +44 -0
  54. package/src/agent_team/atoms/design/contract-freeze.js +8 -0
  55. package/src/agent_team/atoms/design/generation-contract.js +442 -0
  56. package/src/agent_team/atoms/design/reconstruction-pack.js +246 -0
  57. package/src/agent_team/atoms/design/reference-surface-lock.js +49 -0
  58. package/src/agent_team/atoms/patch-challenge.js +19 -0
  59. package/src/agent_team/atoms/pencil/accept.js +9 -0
  60. package/src/agent_team/atoms/pencil/draft.js +365 -0
  61. package/src/agent_team/atoms/pencil/refine.js +229 -0
  62. package/src/agent_team/atoms/phase-run-dispatch.js +8 -0
  63. package/src/agent_team/atoms/team-run.js +380 -0
  64. package/src/agent_team/atoms/visual/aesthetic-review.js +231 -0
  65. package/src/agent_team/atoms/visual/benchmark-repair-plan.js +291 -0
  66. package/src/agent_team/atoms/visual/benchmark.js +1652 -0
  67. package/src/agent_team/atoms/visual/design-selection.js +23 -0
  68. package/src/agent_team/atoms/visual/direction-synthesis.js +124 -0
  69. package/src/agent_team/atoms/visual/dom-rect-export.js +129 -0
  70. package/src/agent_team/atoms/visual/image-diff.js +186 -0
  71. package/src/agent_team/atoms/visual/layout-competition.js +8 -0
  72. package/src/agent_team/atoms/visual/page-evidence-capture.js +806 -0
  73. package/src/agent_team/atoms/visual/playwright-runtime.js +8 -0
  74. package/src/agent_team/atoms/visual/review-aggregate.js +87 -0
  75. package/src/agent_team/atoms/visual/review.js +77 -0
  76. package/src/agent_team/atoms/visual/visual-report.js +197 -0
  77. package/src/agent_team/atoms/visual/visual-token-export.js +417 -0
  78. package/src/agent_team/common.js +311 -0
  79. package/src/core/atoms/agent-invoke.js +684 -0
  80. package/src/core/atoms/event/ingest.js +30 -0
  81. package/src/core/atoms/experience/digest.js +55 -0
  82. package/src/core/atoms/gate/artifact-verify.js +83 -0
  83. package/src/core/atoms/gate/competitor-contract-validate.js +119 -0
  84. package/src/core/atoms/gate/evidence-collect.js +64 -0
  85. package/src/core/atoms/gate/payload-from-phase-run.js +78 -0
  86. package/src/core/atoms/gate/visual-benchmark-validate.js +183 -0
  87. package/src/core/atoms/gate/workbench.js +79 -0
  88. package/src/core/atoms/intake/classify.js +15 -0
  89. package/src/core/atoms/intake/design-skill-select.js +16 -0
  90. package/src/core/atoms/intake/preview-or-refine.js +19 -0
  91. package/src/core/atoms/intake/recommend.js +20 -0
  92. package/src/core/atoms/intake/research-same-category.js +19 -0
  93. package/src/core/atoms/intervention/create.js +30 -0
  94. package/src/core/atoms/memory/manage.js +27 -0
  95. package/src/core/atoms/memory/mount.js +13 -0
  96. package/src/core/atoms/mission/create.js +19 -0
  97. package/src/core/atoms/mission/list.js +14 -0
  98. package/src/core/atoms/mission/show.js +26 -0
  99. package/src/core/atoms/notify/checkpoint.js +46 -0
  100. package/src/core/atoms/phase-run/complete.js +42 -0
  101. package/src/core/atoms/phase-run/fail.js +40 -0
  102. package/src/core/atoms/phase-run/persist.js +39 -0
  103. package/src/core/atoms/phase-run/start.js +30 -0
  104. package/src/core/atoms/plugin/run.js +76 -0
  105. package/src/core/atoms/policy/gate.js +90 -0
  106. package/src/core/atoms/policy/resolve.js +11 -0
  107. package/src/core/atoms/storage/sync.js +57 -0
  108. package/src/core/atoms/workflow/advance.js +25 -0
  109. package/src/core/atoms/workflow/guard.js +127 -0
  110. package/src/core/atoms/workflow/state-load.js +37 -0
  111. package/src/core/bindings.js +37 -0
  112. package/src/core/change-artifacts.js +134 -0
  113. package/src/core/competitive-score.js +265 -0
  114. package/src/core/concurrency-policy.js +35 -0
  115. package/src/core/execution-log.js +108 -0
  116. package/src/core/intake-recommendation.js +134 -0
  117. package/src/core/memory-state.js +62 -0
  118. package/src/core/mission-state.js +780 -0
  119. package/src/core/pending-gates.js +66 -0
  120. package/src/core/phase-cost.js +116 -0
  121. package/src/core/phase-run-read.js +27 -0
  122. package/src/core/policy-overlay.js +180 -0
  123. package/src/core/state-store.js +201 -0
  124. package/src/core/workflow-executor.js +1014 -0
  125. package/src/core/workflow-integrity.js +111 -0
  126. package/src/core/workflow-loader.js +163 -0
  127. package/src/core/workflow-rerun.js +84 -0
  128. package/src/core/workflow-state.js +119 -0
  129. package/src/server.js +1307 -0
  130. package/workflows/corps.yaml +481 -0
  131. package/workflows/yolo.yaml +241 -0
  132. package/xflow/README.md +76 -0
  133. package/xflow/aha/SKILL.md +82 -0
  134. package/xflow/aha/scripts/append_aha.py +50 -0
  135. package/xflow/archive/scripts/archive_change.py +338 -0
  136. package/xflow/archive/templates/merge-design.md +54 -0
  137. package/xflow/archive/templates/merge-workflow.md +26 -0
  138. package/xflow/atoms/__init__.py +6 -0
  139. package/xflow/atoms/a1_issue_create_or_patch.py +70 -0
  140. package/xflow/atoms/a2_branch_create_and_link.py +42 -0
  141. package/xflow/atoms/a3_repo_doctor.py +11 -0
  142. package/xflow/atoms/a4_project_set_status.py +11 -0
  143. package/xflow/atoms/a5_archive_commit_push_close.py +11 -0
  144. package/xflow/atoms/a6_pr_create.py +72 -0
  145. package/xflow/atoms/b1_change_scaffold.py +11 -0
  146. package/xflow/atoms/b2_status_read.py +16 -0
  147. package/xflow/atoms/b2b_status_write.py +20 -0
  148. package/xflow/atoms/b3_status_transition.py +27 -0
  149. package/xflow/atoms/b4_handoff_scaffold_or_refresh.py +11 -0
  150. package/xflow/atoms/b5_aha_append.py +11 -0
  151. package/xflow/atoms/b6_takein_digest.py +11 -0
  152. package/xflow/atoms/b6b_lookback_digest.py +11 -0
  153. package/xflow/atoms/b7_change_mission_bind.py +43 -0
  154. package/xflow/atoms/c1_mem.py +54 -0
  155. package/xflow/atoms/e6_gate_local_precheck.py +23 -0
  156. package/xflow/atoms/h1_design_lite_gate.py +74 -0
  157. package/xflow/atoms/i6a_tdd_run.py +107 -0
  158. package/xflow/atoms/i6b_tdd_proof_validate.py +184 -0
  159. package/xflow/atoms/i6c_tdd_quality_review.py +372 -0
  160. package/xflow/atoms/j1_tests_run.py +129 -0
  161. package/xflow/atoms/j4a_spec_consistency_structural.py +105 -0
  162. package/xflow/atoms/j4b_spec_delta_review.py +316 -0
  163. package/xflow/atoms/j4c_openspec_migration_map.py +121 -0
  164. package/xflow/atoms/j4d_spec_clarify_gate.py +373 -0
  165. package/xflow/atoms/j6_cr_review.py +443 -0
  166. package/xflow/atoms/k1_artifacts_complete_check.py +39 -0
  167. package/xflow/atoms/k2_merge_snippets_apply.py +11 -0
  168. package/xflow/atoms/k3_handoff_refresh.py +14 -0
  169. package/xflow/atoms/k4_mem_lesson_persist.py +65 -0
  170. package/xflow/atoms/k5_archive_publish.py +21 -0
  171. package/xflow/atoms/k6_aha_merge.py +42 -0
  172. package/xflow/atoms/tdd_lib.py +956 -0
  173. package/xflow/corps/SKILL.md +109 -0
  174. package/xflow/exec/scripts/set_issue_in_progress.py +159 -0
  175. package/xflow/goal/SKILL.md +150 -0
  176. package/xflow/handoff/SKILL.md +95 -0
  177. package/xflow/handoff/scripts/scaffold_handoff.py +304 -0
  178. package/xflow/lookback/SKILL.md +66 -0
  179. package/xflow/lookback/scripts/lookback_digest.py +46 -0
  180. package/xflow/openissue/scripts/open_issue_flow.py +438 -0
  181. package/xflow/plan/SKILL.md +47 -0
  182. package/xflow/ralph/SKILL.md +123 -0
  183. package/xflow/scripts/check_installed_xflow_skill_sync.sh +44 -0
  184. package/xflow/scripts/common.py +483 -0
  185. package/xflow/scripts/doctor.py +278 -0
  186. package/xflow/scripts/sync_installed_xflow_skill.sh +134 -0
  187. package/xflow/takein/SKILL.md +81 -0
  188. package/xflow/takein/scripts/takein_digest.py +88 -0
  189. package/xflow/yolo/SKILL.md +75 -0
  190. package/xflow/yolo/scripts/scaffold_specs_change.py +673 -0
  191. package/xflow/yolo/scripts/yolo_gate.py +312 -0
  192. package/xflow/yolo/templates/DESIGN.md +179 -0
@@ -0,0 +1,180 @@
1
+ # evalid Launch Dossier
2
+
3
+ Generated: 2026-11-05T17:36:26.724Z
4
+ Mode: post_publish
5
+ Verdict: conditionally ready: engine and adoption evidence are strong, registry publication remains required for a splash launch
6
+ Launch ready: not yet
7
+ Splash verdict: conditionally ready: engine and maintainer adoption evidence are strong, but third-party adoption and registry publication remain required for an industry-splash launch
8
+ Splash launch ready: not yet
9
+ Competitive score: 100/100
10
+
11
+ ## Quality Judgment
12
+
13
+ strong, launch-ready after registry publish; adoption evidence is now non-fixture but third-party proof remains the next ecosystem win
14
+
15
+ Codex native goal comparison: xflow can beat Codex native goal at the project layer, not as a thread reminder.
16
+
17
+ ## Surface Scorecard
18
+
19
+ | Surface | Grade | Why | Next win |
20
+ | --- | --- | --- | --- |
21
+ | xflow:goal | A | Durable .xflow/GOAL.md anchor with CLI access, cross-tool portability, and machine-readable goal audit. | Collect real project examples where goal alignment changed handoff or review quality. |
22
+ | xflow:yolo | A | Lite workflow is executable YAML with split red/green TDD proof, quality review, archive order, and drift coverage. | Publish a tiny external repo walkthrough that shows a real bugfix from red proof to archive. |
23
+ | xflow:corps | A | Heavy workflow has governed proof, visual benchmark gates, no-stub runtime witnesses, control-plane observability, and a first-time operator guide. | Publish a third-party product/UI adoption walkthrough backed by corps proof. |
24
+ | skill family | A- | The ladder now reads goal -> takein -> plan -> yolo/corps -> ralph -> handoff/aha, with sync and diff checks. | Publish the package and collect third-party adoption evidence beyond maintainer dogfooding. |
25
+
26
+ ## Objective Audit
27
+
28
+ - `goal_vs_codex`: proven_project_layer
29
+ - `yolo_delivery`: proven_from_source
30
+ - `corps_delivery`: proven_from_source
31
+ - `skill_family_open_source_credibility`: ready_from_source_checkout
32
+ - `open_source_launch`: blocked
33
+ - `industry_splash`: blocked
34
+
35
+ ## Demo Proof Paths
36
+
37
+ ### Goal to yolo
38
+
39
+ Use when: backend, docs, infra, and small UI changes
40
+
41
+ Commands:
42
+ - `xflow guide`
43
+ - `xflow assess`
44
+ - `xflow init --project-root .`
45
+ - `xflow goal set "Ship the next verified change" --project-root .`
46
+ - `xflow goal audit --project-root . --json`
47
+ - `xflow workflow validate yolo --project-root .`
48
+ - `xflow workflow run yolo --project-root . --title "Example verified change" --change-type backend --tdd-red-command "npm test -- --grep new-behavior" --tdd-green-command "npm test"`
49
+
50
+ Evidence:
51
+ - `.xflow/GOAL.md`
52
+ - `xflow goal audit --json`
53
+ - `specs/changes/<change-id>/tdd/red-0.json`
54
+ - `specs/changes/<change-id>/tdd/green-0.json`
55
+ - `specs/changes/<change-id>/tdd/quality-0.json`
56
+ - `HANDOFF.md`
57
+
58
+ ### Goal to corps proof
59
+
60
+ Use when: product, UI, competitor-led, or multi-agent work
61
+
62
+ Commands:
63
+ - `xflow goal show --json`
64
+ - `xflow goal audit --json`
65
+ - `xflow corps --title "Competitor-aligned workbench" --change-type frontend --change-id launch-corps-demo --capture-url http://127.0.0.1:4174/ --reference-image refs/competitor-main.png --dry-run --json`
66
+ - `xflow proof --track corps --change-id launch-corps-demo`
67
+
68
+ Evidence:
69
+ - `.xflow/GOAL.md`
70
+ - `xflow goal audit --json`
71
+ - `specs/changes/launch-corps-demo/visual_benchmark.json`
72
+ - `specs/changes/launch-corps-demo/corps_proof.json`
73
+ - `hash-linked execution log witnesses`
74
+ - `final goal-alignment review`
75
+
76
+ ## Runnable Examples
77
+
78
+ - `docs/examples-gallery.md` maps clean adoption smoke, goal-to-yolo, goal-to-corps proof, external tracker import, and release gate examples.
79
+ - Use `xflow demo launch --json` for the machine-readable launch path summary.
80
+
81
+ ## Release Gate
82
+
83
+ - `npm run release:pack`
84
+ - `npm run publish:check`
85
+ - `xflow evaluate --json`
86
+ - `xflow release status --json`
87
+ - `xflow adoption trial --name <team-or-project> --source <tracker-or-pr> --track yolo --json`
88
+ - `xflow goal audit --json`
89
+ - `xflow adoption status --json`
90
+ - `xflow adoption validate --json`
91
+ - `xflow launch claims --json`
92
+ - `xflow launch copy --json`
93
+ - `xflow package status --json`
94
+ - `xflow package preflight --check-registry --check-auth --json`
95
+ - `xflow package audit --check-registry --json`
96
+ - `xflow launch audit --strict --json`
97
+ - `xflow launch audit --splash --strict --json`
98
+ - `git status --short --branch`
99
+
100
+ ## Missing Before Ordinary Launch
101
+
102
+ - **published_package**: Public npm package ownership confirmed and package published from a green dry run.
103
+ Why it matters: A launch story is incomplete while users cannot install the advertised package name.
104
+ Acceptable evidence: npm view @surlymochan/evalid name version --json returns this package; npm publish --access public completed for the intended version
105
+
106
+ ## Missing Before Splash Launch
107
+
108
+ - **third_party_adoption**: At least one adoption artifact comes from a third-party project, public PR, external repository, or named external team beyond maintainer dogfooding.
109
+ Why it matters: An industry-splash claim needs ecosystem evidence, not only a maintainer hardening run inside evalid.
110
+ Acceptable evidence: docs/adoption/<third-party-project>.md with a public PR, external repository, or named external team source; xflow adoption validate --splash --json passes; xflow launch audit --splash --strict --json passes
111
+ - **published_package**: Public npm package ownership confirmed and package published from a green dry run.
112
+ Why it matters: A launch story is incomplete while users cannot install the advertised package name.
113
+ Acceptable evidence: npm view @surlymochan/evalid name version --json returns this package; npm publish --access public completed for the intended version
114
+
115
+ ## Current Evidence Snapshot
116
+
117
+ - Adoption records: 1; status: pass
118
+ - Goal audit: pass; goal: Keep evalid credible as an open-source agent delivery runtime: repo-owned workflow contracts, executable verification gates, durable project context, and honest benchmark evidence.
119
+ - Package evidence: missing; source: registry_json
120
+ - Package name/version: @surlymochan/evalid@0.4.1
121
+
122
+ ## Passing Evidence
123
+
124
+ - `xflow assess --json`
125
+ - `xflow score --json`
126
+ - `xflow goal audit --json`
127
+ - `xflow adoption validate --json`
128
+
129
+ ## Available Checks
130
+
131
+ - `xflow quickstart --json`
132
+ - `xflow evaluate --json`
133
+ - `xflow release status --json`
134
+ - `xflow assess --json`
135
+ - `xflow demo launch --json`
136
+ - `xflow launch claims --json`
137
+ - `xflow launch copy --json`
138
+ - `xflow score --json`
139
+ - `xflow goal audit --json`
140
+ - `xflow adoption status --json`
141
+ - `npm run release:pack`
142
+ - `npm run publish:check`
143
+ - `xflow package status --json`
144
+ - `xflow package preflight --check-registry --check-auth --json`
145
+ - `xflow package audit --check-registry --json`
146
+
147
+ ## Next Actions For Ordinary Launch
148
+
149
+ - **verify_release_pack**: `npm run release:pack`
150
+ Reason: Re-run the full local release pack immediately before any publish attempt.
151
+ - **check_package_preflight**: `xflow package preflight --check-registry --check-auth --json`
152
+ Reason: Verify npm identity plus package-name/version availability without publishing.
153
+ - **run_pre_publish_launch_audit**: `xflow launch audit --pre-publish --strict --json`
154
+ Reason: Prove score, adoption evidence, npm identity, and package availability before the irreversible publish step.
155
+ - **publish_package**: `npm publish --access public`
156
+ Reason: Run only after release:pack, package preflight, and pre-publish launch audit are green.
157
+ - **verify_registry_publication**: `xflow package audit --check-registry --json`
158
+ Reason: Prove the public npm registry reports the expected package name and version before claiming npm install readiness.
159
+ - **rerun_launch_audit**: `xflow launch audit --strict --json`
160
+ Reason: Close the post-publish launch gate after registry evidence is visible.
161
+
162
+ ## Next Actions For Splash Launch
163
+
164
+ - **record_third_party_adoption**: `xflow adoption kit --name <third-party-project> --source <public-pr-or-external-repo> --track yolo`
165
+ Reason: Industry-splash claims require a third-party trial packet that becomes reviewable evidence beyond maintainer dogfooding.
166
+ - **validate_splash_adoption**: `xflow adoption validate --splash --json`
167
+ Reason: Remove the third_party_adoption gap only after a third-party record passes validation.
168
+ - **verify_release_pack**: `npm run release:pack`
169
+ Reason: Re-run the full local release pack immediately before any publish attempt.
170
+ - **check_package_preflight**: `xflow package preflight --check-registry --check-auth --json`
171
+ Reason: Verify npm identity plus package-name/version availability without publishing.
172
+ - **run_pre_publish_launch_audit**: `xflow launch audit --pre-publish --strict --json`
173
+ Reason: Prove score, adoption evidence, npm identity, and package availability before the irreversible publish step.
174
+ - **publish_package**: `npm publish --access public`
175
+ Reason: Run only after release:pack, package preflight, and pre-publish launch audit are green.
176
+ - **verify_registry_publication**: `xflow package audit --check-registry --json`
177
+ Reason: Prove the public npm registry reports the expected package name and version before claiming npm install readiness.
178
+ - **rerun_launch_audit**: `xflow launch audit --strict --json`
179
+ Reason: Close the post-publish launch gate after registry evidence is visible.
180
+
@@ -0,0 +1,149 @@
1
+ # xflow Methodology
2
+
3
+ Date: 2026-04-19
4
+
5
+ ## Purpose
6
+
7
+ xflow should feel like a guided delivery loop, not a bag of internal atoms. Operators should know what to do next even when they do not know the workflow internals.
8
+
9
+ The loop is:
10
+
11
+ ```text
12
+ shape -> choose-track -> execute -> review -> finish
13
+ ```
14
+
15
+ Use `xflow guide` when you need the shortest reminder of this loop.
16
+
17
+ ## 1. Shape The Work
18
+
19
+ Goal: turn a rough request into a readable problem frame before implementation.
20
+
21
+ Use:
22
+
23
+ ```bash
24
+ xflow:plan
25
+ ```
26
+
27
+ Expected artifacts:
28
+
29
+ - `proposal.md`
30
+ - `plan.md`
31
+
32
+ Rules:
33
+
34
+ - Keep planning track-neutral.
35
+ - Do not choose yolo or corps inside plan.
36
+ - Reuse an existing current `plan.md` when yolo or corps starts.
37
+
38
+ ## 2. Choose The Delivery Track
39
+
40
+ Goal: select the smallest track that can safely complete the work.
41
+
42
+ Use `xflow:yolo` when the change is bounded:
43
+
44
+ - backend logic
45
+ - docs
46
+ - scripts
47
+ - infrastructure
48
+ - small UI changes without a design loop
49
+
50
+ Use `xflow:corps` when the change needs heavier coordination:
51
+
52
+ - complex UI or product work
53
+ - multi-agent execution
54
+ - visual review
55
+ - mission control and gate observability
56
+
57
+ CLI equivalents:
58
+
59
+ ```bash
60
+ xflow workflow validate yolo
61
+ xflow workflow validate corps
62
+ ```
63
+
64
+ `workflow validate` is preflight only. It must not be used as proof that
65
+ `xflow:corps` ran.
66
+
67
+ ## 3. Execute With Gates
68
+
69
+ Goal: move work through deterministic phases while preserving evidence.
70
+
71
+ Use:
72
+
73
+ ```bash
74
+ xflow workflow run yolo --title "<title>" --change-type backend
75
+ ```
76
+
77
+ or:
78
+
79
+ ```bash
80
+ xflow corps --title "<title>" --change-type frontend --change-id <id>
81
+ xflow proof --track corps --change-id <id>
82
+ ```
83
+
84
+ Expected artifacts:
85
+
86
+ - `status.json`
87
+ - `verify_proof.json`
88
+ - `corps_proof.json` for heavy-track completion
89
+ - workflow logs
90
+ - phase outputs under `specs/changes/<change-id>/`
91
+
92
+ Rules:
93
+
94
+ - Gates are stop signs, not decoration.
95
+ - Human gates require explicit approval.
96
+ - Verification evidence should be produced before archive.
97
+ - `corps` completion requires the governed built-in workflow manifest, hash-linked execution-log witnesses for every canonical phase, successful atom/gate evidence, and no `stub`, `task_queued`, or `pencil_stubbed` fallback.
98
+ - TDD is a first-class gate: the red proof runs before implementation, the green proof runs after implementation, and quality review rejects code changes without meaningful changed tests.
99
+
100
+ ## 4. Review The Evidence
101
+
102
+ Goal: make completion defensible before shipping or handing off.
103
+
104
+ Run:
105
+
106
+ ```bash
107
+ npm test
108
+ npm run drift:scan
109
+ npm run skill:diff
110
+ xflow score
111
+ ```
112
+
113
+ Review:
114
+
115
+ - `docs/reviewer-guide.md`
116
+ - `verify_proof.json`
117
+ - `HANDOFF.md`
118
+ - current git status
119
+
120
+ ## 5. Finish And Preserve Context
121
+
122
+ Goal: close the loop without losing durable learning.
123
+
124
+ Archive ownership stays with:
125
+
126
+ ```text
127
+ A5.archive.commit_push_close
128
+ ```
129
+
130
+ Expected durable outputs:
131
+
132
+ - refreshed `HANDOFF.md`
133
+ - updated `AHA.md` when there is a durable insight
134
+ - merged spec/workflow deltas
135
+ - committed and pushed implementation
136
+
137
+ ## How This Beats Prompt-Only Workflows
138
+
139
+ xflow does not rely on a remembered chat ritual. The methodology is backed by:
140
+
141
+ - executable YAML workflows
142
+ - schema and registry tests
143
+ - local readiness checks
144
+ - drift scans
145
+ - installed skill sync checks
146
+ - handoff and archive artifacts
147
+ - `xflow score` evidence
148
+
149
+ The result is a workflow that is understandable to humans and enforceable by tooling.
@@ -0,0 +1,96 @@
1
+ # npm Publish Handoff
2
+
3
+ Date: 2026-05-23
4
+
5
+ Use this page for the final irreversible public publish step. Everything here
6
+ is intentionally explicit because `npm publish --access public` changes public
7
+ distribution state.
8
+
9
+ ## Automated publish (trusted publishing)
10
+
11
+ The registry-mutating step normally runs from GitHub Actions, not from a
12
+ local shell: `.github/workflows/npm-publish.yml` publishes via npm trusted
13
+ publishing (OIDC — no stored npm token anywhere) whenever a GitHub Release
14
+ is published, and can also be started manually (workflow_dispatch) to
15
+ publish the version in `package.json` if that version is not on npm yet.
16
+ Before publishing it runs the same `npm run release:pack` gate as the manual
17
+ sequence below, and for release events it refuses to publish when the
18
+ release tag does not match the `package.json` version. The manual sequence
19
+ below remains the fallback for when Actions or the trusted-publisher
20
+ registration on npmjs.com is unavailable.
21
+
22
+ ## Current Verified State
23
+
24
+ - Package: `evalid@0.2.0`
25
+ - Registry name status: available in `xflow package preflight --check-registry --check-auth --json`
26
+ - Current machine auth: blocked by `npm whoami` with `ENEEDAUTH`
27
+ - Adoption gate: `xflow adoption validate --json` passes with
28
+ `docs/adoption/openflow-release-hardening.md`
29
+ - Splash gate: `xflow release status --json` still reports
30
+ `third_party_adoption` alongside `published_package`; use
31
+ `xflow adoption brief --name <third-party-project> --source <public-pr-or-external-repo> --track yolo`
32
+ to generate the outbound ask, then
33
+ `xflow adoption trial --name <third-party-project> --source <public-pr-or-external-repo> --track yolo`
34
+ before asking an external team to create reviewable evidence.
35
+ - Launch gate: `xflow launch audit --strict --json` still lists only
36
+ `published_package`
37
+
38
+ Do not claim public installability until the registry reports `evalid@0.2.0`.
39
+
40
+ ## Auth Recovery
41
+
42
+ ```bash
43
+ npm login
44
+ npm whoami
45
+ xflow package status --json
46
+ xflow package preflight --check-registry --check-auth --json
47
+ ```
48
+
49
+ The preflight must report:
50
+
51
+ - `ok: true`
52
+ - `registry_status: "available"` for a first publish
53
+ - a non-empty `npm_identity`
54
+ - no `registry already contains evalid@0.2.0` issue
55
+ - `next_actions` containing `run_pre_publish_gate` as the next release-owner
56
+ command
57
+
58
+ ## Final Publish Sequence
59
+
60
+ Run from the repository root after npm auth is restored:
61
+
62
+ ```bash
63
+ npm run release:pack
64
+ npm run publish:check
65
+ xflow release status --json
66
+ xflow adoption brief --name <third-party-project> --source <public-pr-or-external-repo> --track yolo
67
+ xflow adoption trial --name <third-party-project> --source <public-pr-or-external-repo> --track yolo
68
+ xflow adoption validate --json
69
+ xflow goal audit --json
70
+ xflow package status --json
71
+ xflow package preflight --check-registry --check-auth --json
72
+ xflow launch audit --pre-publish --strict --json
73
+ npm publish --access public
74
+ xflow package audit --check-registry --json
75
+ xflow launch audit --strict --json
76
+ ```
77
+
78
+ The real publish is allowed only after the pre-publish launch audit is green.
79
+ After publish, the strict launch audit is allowed to become green only when
80
+ `xflow package audit --check-registry --json` confirms the public registry
81
+ returns the expected name and version.
82
+
83
+ ## Stop Conditions
84
+
85
+ - `npm whoami` fails: restore npm auth first.
86
+ - Registry already contains `evalid@0.2.0`: do not republish; bump version or
87
+ verify ownership before continuing.
88
+ - `xflow package preflight --check-registry --check-auth --json` fails: follow
89
+ its `next_actions` before retrying or publishing.
90
+ - `npm run release:pack` fails: fix local quality before publishing.
91
+ - `xflow adoption validate --json` fails: restore a non-fixture adoption record.
92
+ - `xflow launch audit --pre-publish --strict --json` fails: do not publish.
93
+ - `xflow package audit --check-registry --json` fails after publish: follow its
94
+ `next_actions`; do not claim public installability until it passes.
95
+ - `npm publish --dry-run --access public` includes test fixtures, Python caches,
96
+ local `.as-xflow/` state, or secrets: fix package inclusion before publishing.
@@ -0,0 +1,106 @@
1
+ # OpenSpec Migration Guide
2
+
3
+ Use this guide when moving an OpenSpec-style project into evalid, or when explaining how the two systems map.
4
+
5
+ OpenSpec is strongest as a lightweight spec-driven development surface. evalid keeps that spec discipline, then adds executable workflow gates, TDD proof, test-quality review, archive ordering, handoff, and release checks.
6
+
7
+ ## Safe Mapping Command
8
+
9
+ Run this first. It does not move or rewrite files.
10
+
11
+ ```bash
12
+ xflow spec openspec-map --project-root . --openspec-root openspec
13
+ xflow spec start --title "example change" --change-type backend
14
+ xflow spec quick "example change"
15
+ xflow spec delta --project-root . --change-id <id>
16
+ ```
17
+
18
+ First command output:
19
+
20
+ ```text
21
+ .as-xflow/openspec-migration.json
22
+ ```
23
+
24
+ The report maps:
25
+
26
+ - `openspec/specs/*.md` to durable `specs/*.md`
27
+ - `openspec/changes/<change>/proposal.md` to `specs/changes/<change-id>/proposal.md`
28
+ - `openspec/changes/<change>/design.md` to design context or change notes
29
+ - accepted OpenSpec scope and design decisions to `specs/changes/<id>/plan.md`
30
+ - `openspec/changes/<change>/tasks.md` to `specs/changes/<change-id>/tasks.md`
31
+ - OpenSpec change folders to xflow `change_id` values
32
+
33
+ ## Command Mapping
34
+
35
+ | OpenSpec | evalid |
36
+ | --- | --- |
37
+ | `openspec init` | `xflow init --project-root .` |
38
+ | `/opsx:new <change>` | `xflow spec quick "<title>"` or `xflow spec start --title "<title>" --change-type <type>` |
39
+ | `/opsx:ff` | `xflow:plan` creates or refreshes `plan.md` |
40
+ | `/opsx:apply` | `xflow workflow run yolo|corps --project-root .` |
41
+ | `/opsx:archive` | xflow archive phase through `A5.archive.commit_push_close` |
42
+ | OpenSpec spec delta review | `xflow spec delta --change-id <id>` |
43
+
44
+ ## Folder Mapping
45
+
46
+ | OpenSpec Path | evalid Path | Notes |
47
+ | --- | --- | --- |
48
+ | `openspec/specs/` | `specs/` | Durable root specs. Keep stable, reviewed, and human-readable. |
49
+ | `openspec/changes/<id>/proposal.md` | `specs/changes/<id>/proposal.md` | Preserved as change intent. |
50
+ | `openspec/changes/<id>/design.md` | `specs/changes/<id>/design.md` or `DESIGN.md` | Use root `DESIGN.md` for active frontend design contract. |
51
+ | accepted OpenSpec scope/design | `specs/changes/<id>/plan.md` | Canonical reusable xflow implementation plan. |
52
+ | `openspec/changes/<id>/tasks.md` | `specs/changes/<id>/tasks.md` | Optional working checklist; xflow:plan writes `plan.md` as the canonical plan. |
53
+ | `openspec/changes/<id>/specs/` | `merge-product.md`, `merge-architecture.md`, `merge-workflow.md` | Archive-ready spec snippets. |
54
+
55
+ ## Spec Delta Review
56
+
57
+ Run:
58
+
59
+ ```bash
60
+ xflow spec delta --project-root . --change-id <id>
61
+ ```
62
+
63
+ Output:
64
+
65
+ ```text
66
+ specs/changes/<id>/spec_delta_review.json
67
+ specs/changes/<id>/spec_delta_review.md
68
+ ```
69
+
70
+ The review summarizes:
71
+
72
+ - proposal headings and intent bullets
73
+ - plan sections and verification commands
74
+ - task counts and completed task counts
75
+ - merge spec snippets that will affect durable root specs
76
+ - warnings such as missing verification commands or missing merge spec snippets
77
+
78
+ ## Migration Strategy
79
+
80
+ 1. Run `xflow init --project-root .`.
81
+ 2. Run `xflow spec openspec-map --project-root . --openspec-root openspec`.
82
+ 3. Review `.as-xflow/openspec-migration.json`.
83
+ 4. Copy durable OpenSpec specs into `specs/` only after human review.
84
+ 5. Copy active OpenSpec changes into `specs/changes/<change-id>/`.
85
+ 6. Run `xflow spec quick "<change title>"` for the fastest scaffold, or `xflow spec start --title "<change title>" --change-id <change-id>` when you need tighter control.
86
+ 7. Run `xflow spec delta --change-id <change-id>`.
87
+ 8. Run `xflow workflow validate yolo --project-root .`.
88
+ 9. Use `xflow:yolo` or `xflow:corps` for execution.
89
+
90
+ ## What Not To Migrate Blindly
91
+
92
+ - Do not overwrite existing `specs/*.md` without reviewing durable conflicts.
93
+ - Do not turn every OpenSpec task checklist into the canonical xflow plan; `plan.md` remains the reusable implementation plan.
94
+ - Do not skip TDD proof. OpenSpec specs explain intent; xflow proof verifies behavior.
95
+ - Do not bypass archive. Durable spec deltas should land through the archive boundary.
96
+
97
+ ## Why This Beats A Pure OpenSpec Flow
98
+
99
+ OpenSpec is excellent at making intent explicit before implementation. evalid keeps that benefit and adds:
100
+
101
+ - executable workflow validation
102
+ - deterministic spec delta review artifacts
103
+ - red/green TDD proof
104
+ - test-quality proof
105
+ - archive ordering and PR publish boundary
106
+ - release-pack verification
@@ -0,0 +1,68 @@
1
+ # Public Benchmark And Demo
2
+
3
+ This benchmark is the public, repeatable proof path for claims against OpenSpec, gstack, spec-kit, and prompt-only skill systems.
4
+
5
+ ## Demo Scenario
6
+
7
+ A tracker item arrives from an external system. `evalid` imports the source context, turns it into local change artifacts, reviews spec deltas, and proves the release surface before any public claim or package publish.
8
+
9
+ ## Commands
10
+
11
+ ```bash
12
+ xflow init --project-root .
13
+ xflow spec start --title "release proof adapter" --change-type backend
14
+ xflow objective --json
15
+ xflow assess --json
16
+ xflow demo launch --json
17
+ xflow launch dossier
18
+ xflow launch claims --json
19
+ xflow launch copy --json
20
+ xflow goal audit --json
21
+ xflow corps --explain --json
22
+ xflow adoption trial --name <team-or-project> --source <tracker-or-pr> --track yolo
23
+ xflow launch audit --strict --json
24
+ xflow doctor --project-root .
25
+ xflow adapter import-file --project-root . --input docs/fixtures/tracker-item.json --json
26
+ xflow spec delta --change-id release-proof-adapter
27
+ xflow compare codex-goal
28
+ xflow compare gstack
29
+ xflow compare superpowers
30
+ xflow compare super-assistant
31
+ xflow compare openspec
32
+ xflow compare spec-kit
33
+ xflow score
34
+ npm run publish:check
35
+ xflow package preflight --check-registry --check-auth --json
36
+ xflow launch audit --pre-publish --strict --json
37
+ ```
38
+
39
+ ## Expected Artifacts
40
+
41
+ | Artifact | Meaning |
42
+ | --- | --- |
43
+ | `.as-xflow/config.json` | Project-local workflow defaults. |
44
+ | `specs/changes/release-proof-adapter/proposal.md` | Imported tracker context, now owned by repo-local xflow artifacts. |
45
+ | `specs/changes/release-proof-adapter/status.json` | Draft workflow state and adapter provenance. |
46
+ | `specs/changes/release-proof-adapter/spec_delta_review.json` | Requirements-level spec delta review. |
47
+ | `npm pack --dry-run` output | Package whitelist proof. |
48
+
49
+ ## Scoring Method
50
+
51
+ | Dimension | Passing Evidence |
52
+ | --- | --- |
53
+ | Local engineering closure | `xflow workflow validate yolo`, `xflow workflow validate corps`, archive atoms, release pack. |
54
+ | TDD quality pressure | `I6a.tdd.run`, `I6b.tdd.proof_validate`, `I6c.tdd.quality_review`, and `test/tdd-proof.test.js`. |
55
+ | gstack comparison | `docs/gstack-comparison.md` and `xflow compare gstack --json`. |
56
+ | Superpowers comparison | `docs/superpowers-comparison.md` and `xflow compare superpowers --json`. |
57
+ | Super-Assistant comparison | `docs/super-assistant-comparison.md` and `xflow compare super-assistant --json`. |
58
+ | OpenSpec migration | `xflow spec openspec-map`, `docs/openspec-migration.md`, and `xflow spec delta`. |
59
+ | Spec authoring flow | `xflow spec start`, `docs/openspec-migration.md`, and generated `specs/changes/<id>/` artifacts. |
60
+ | spec-kit comparison | `docs/spec-kit-benchmark.md`, `docs/integrations.md`, and `xflow compare spec-kit --json`. |
61
+ | Public product readiness | README badges, `RELEASE_NOTES.md`, `docs/fixtures/tracker-item.json`, package whitelist, `npm run publish:check`, `xflow package status --json`, `xflow package preflight --check-registry --check-auth --json`, and `xflow package audit --check-registry --json`. |
62
+ | Quality assessment | `xflow assess --json`, `docs/quality-assessment.md`, `docs/goal-vs-codex.md`, `xflow compare codex-goal --json`, `xflow goal audit --json`, and `xflow score --json`. |
63
+ | Launch demo | `xflow demo launch --json`, `xflow corps --explain --json`, `xflow launch dossier`, `docs/launch-demo.md`, `docs/launch-dossier.md`, `docs/examples-gallery.md`, `docs/corps-operator-guide.md`, and goal-to-yolo / goal-to-corps proof paths. |
64
+ | Launch readiness | `xflow evaluate --json` with `splash_launch` and `splash_claims`, `xflow goal audit --json`, `xflow launch claims --json`, `xflow launch claims --splash --json`, `xflow launch copy --json`, `xflow launch copy --splash --json`, `xflow launch audit --pre-publish --strict --json`, `xflow launch audit --strict --json`, `xflow launch audit --splash --strict --json`, `xflow adoption status --json`, `xflow adoption trial`, `xflow adoption validate --json`, `xflow adoption validate --splash --json`, `xflow package status --json`, `xflow package preflight --check-registry --check-auth --json`, `xflow package audit --check-registry --json`, `docs/public-release.md`, `docs/npm-publish-handoff.md`, `docs/adoption/README.md`, `docs/adoption/openflow-release-hardening.md`, and explicit missing registry proof. |
65
+
66
+ ## Current Result
67
+
68
+ `evalid` is designed to win the local delivery and verification benchmark because every superiority claim is backed by a runnable command or checked file. Public ecosystem breadth still needs third-party adoption, but the repo now ships the adapter seam, adoption validator, fixture-backed smoke path, and a non-fixture maintainer release-hardening adoption record.