@surlymochan/evalid 0.0.0-stage → 0.3.1

package/docs/adoption/README.md

@@ -0,0 +1,128 @@
+# Adoption Evidence
+
+Use this folder for real external adoption proof. Do not use it for fixture-only
+demo runs, synthetic screenshots, or private anecdotes that cannot be reviewed.
+
+`xflow launch audit --json` intentionally treats public launch as incomplete
+until at least one adoption artifact exists here or a linked public PR provides
+equivalent evidence.
+
+Validate records before using them in launch claims:
+
+```bash
+xflow adoption brief --name <team-or-project> --source <tracker-or-pr> --track yolo
+xflow adoption trial --name <team-or-project> --source <tracker-or-pr> --track yolo
+xflow adoption kit --name <team-or-project> --source <tracker-or-pr> --track yolo
+xflow adoption init --name <team-or-project> --source <tracker-or-pr> --track yolo
+xflow adoption status --json
+xflow adoption validate --json
+xflow adoption validate --splash --json
+```
+
+`xflow adoption status` is the non-failing release-owner view: it reports
+ordinary adoption status, splash third-party status, blocker ids, and the next
+external trial command without treating missing evidence as a CLI error.
+
+`xflow adoption brief` prints a sendable third-party ask: what to ask for, what
+acceptance bar to hold, and which maintainer follow-up commands close the loop.
+Use it when you need to message an external team instead of just reading raw
+commands yourself.
+
+`xflow adoption trial` prints a copy-paste external trial sequence without
+writing files. Use it when a third-party team asks what to run before you create
+or send a packet.
+
+`xflow adoption kit` creates `docs/adoption/trial-packets/<team-or-project>.md`.
+Share that packet with the external project before the trial. It lists the
+commands to run, the sendable ask text, the artifacts to collect, the
+acceptance bar, and the validation commands that must pass after evidence is
+converted into an adoption record.
+
+`xflow adoption init` only creates a draft. The draft intentionally contains
+placeholders and must fail validation until a real trial fills in evidence,
+outcome, and redaction details.
+
+## Required Shape
+
+Each adoption record should be a short markdown file named after the project,
+team, or tracker source:
+
+```text
+docs/adoption/<team-or-project>.md
+```
+
+The record must include:
+
+- **Context**: what project, team, or external workflow tried xflow.
+- **Goal**: the `.xflow/GOAL.md` direction or equivalent project objective.
+- **Track**: yolo, corps, or both.
+- **Evidence**: commands run, artifacts produced, and links or paths to proof.
+- **Outcome**: what improved, what failed, and whether xflow would be used again.
+- **Redactions**: what was sanitized and why.
+
+## Acceptance Bar
+
+An adoption record is strong enough for launch only when it proves all of these:
+
+1. The work came from outside the fixture path in `docs/fixtures/`.
+2. A real goal or tracker item shaped the delivery.
+3. At least one xflow command produced reviewable artifacts.
+4. The record names a concrete benefit or a concrete failure.
+5. A reviewer can follow the evidence without private machine state.
+
+For industry-splash claims, the bar is stricter: at least one passing record
+must come from a third-party project, public PR, external repository, or named
+external team beyond maintainer dogfooding. Use `xflow launch audit --splash
+--strict --json` before saying broad third-party adoption is proven.
+
+## Template
+
+```markdown
+# Adoption: <team-or-project>
+
+Date: YYYY-MM-DD
+Source: <tracker, repository, team workflow, or public PR>
+Track: <yolo|corps|both>
+
+## Context
+
+<What external project or team workflow tried xflow?>
+
+Use `third-party`, `public PR`, `external project`, `external repository`,
+`customer`, `partner`, `team workflow`, or an `https://` source when the record
+is intended to satisfy splash-launch third-party evidence.
+
+## Goal
+
+<What durable project direction or tracker objective guided the work?>
+
+## Commands
+
+```bash
+xflow goal show --json
+xflow assess --json
+xflow workflow validate yolo --project-root .
+# or: xflow corps ... && xflow proof --track corps --change-id <id>
+```
+
+## Evidence
+
+- `<path-or-link-to-status.json>`
+- `<path-or-link-to-red-green-quality-proof>`
+- `<path-or-link-to-corps_proof.json>`
+- `<path-or-link-to-PR-or-review>`
+
+At least one evidence bullet must be reviewable by someone outside the authoring
+machine. Prefer public PRs, external repository links, sanitized tracker exports,
+or checked-in proof artifacts.
+
+## Outcome
+
+<What got better, what failed, and whether the team would use xflow again?>
+
+## Redactions
+
+<What was sanitized?>
+
+State `None` only when the record and evidence are already public.
+```

package/docs/adoption/openflow-release-hardening.md

@@ -0,0 +1,61 @@
+# Adoption: OpenFlow release hardening
+
+Date: 2026-05-25
+Source: OpenFlow maintainer release-hardening workflow, public commit 9344633
+Track: corps
+
+## Context
+
+The OpenFlow maintainer workflow used xflow itself to extract and harden the
+public launch surface for the heavy `corps` track. The work was not a fixture
+run: it produced a public source repository, documentation, CLI evidence,
+workflow checks, benchmark reporting, and CI verification.
+
+## Goal
+
+Evaluate whether `xflow:goal`, `xflow:yolo`, and `xflow:corps` can provide a
+credible open-source project-delivery layer, then keep the public boundary
+honest about what is proven locally versus what still needs external adoption
+or npm registry proof.
+
+## Commands
+
+```bash
+xflow goal show --json
+xflow goal audit --json
+xflow corps --explain --json
+xflow assess --json
+xflow score --json
+node --test test/cli-usability.test.js test/competitive-readiness.test.js test/workflow-drift-scan.test.js
+SKILL_SYNC_TARGET_DIRS="$HOME/.agents/skills
+$HOME/.codex/skills
+$HOME/.config/opencode/skills" npm run skill:sync
+npm run release:pack
+xflow launch audit --strict --json
+```
+
+## Evidence
+
+- `https://github.com/surlymochan/openflow/commit/9344633`
+- `docs/corps-operator-guide.md`
+- `bin/xflow.js`
+- `test/cli-usability.test.js`
+- `test/competitive-readiness.test.js`
+- `docs/quality-assessment.md`
+- `docs/public-benchmark.md`
+
+## Outcome
+
+The release review got better because the public extraction has a first-time
+operator guide, a CLI `--explain` path, score evidence, CI, and tests that fail
+if core launch documentation disappears. The workflow also kept claim safety
+explicit: source-checkout quality can be proven now, while npm publication and
+third-party adoption claims require separate evidence. A future release owner
+would use this gate again because it separates local quality from distribution
+and ecosystem evidence.
+
+## Redactions
+
+Local home-directory paths and machine-specific command output were summarized.
+No secrets, tokens, private customer data, or private tracker content were
+included.

package/docs/benchmark-openflow-vs-gstack-superpowers-openspec-2026-05-25.md

@@ -0,0 +1,81 @@
+# OpenFlow vs gstack vs Superpowers vs OpenSpec Benchmark
+
+Date: 2026-05-25
+
+This benchmark is a source-checkout, command-driven comparison. It is not a
+neutral industry certification. Scores use OpenFlow's repo-owned delivery
+runtime rubric: executable workflow state, verification gates, handoff,
+auditability, packaging, and claim safety.
+
+## Tested Revisions
+
+| Project | Source | Revision / Version |
+| --- | --- | --- |
+| OpenFlow | local public extraction | `openflow@0.1.0` |
+| gstack | https://github.com/garrytan/gstack | `920a13a17f463c28a3db75cc27482affb13a4fee`, package `1.44.0.0` |
+| Superpowers | https://github.com/obra/superpowers | `f2cbfbefebbfef77321e4c9abc9e949826bea9d7`, package `5.1.0` |
+| OpenSpec | https://github.com/Fission-AI/OpenSpec | `e441287b1fdd719bfa4518936c79e03e91c8d3c9`, package `@fission-ai/openspec@1.3.1` |
+
+## Commands Actually Run
+
+| Project | Command | Result | Notes |
+| --- | --- | --- | --- |
+| OpenFlow | `npm ci` | Pass | Installed local package dependencies. |
+| OpenFlow | `node bin/xflow.js doctor --project-root . --json` | Pass | 12/12 readiness checks passed. |
+| OpenFlow | `node bin/xflow.js workflow validate yolo --project-root . --json` | Pass | Public yolo workflow validates. |
+| OpenFlow | `node bin/xflow.js score --json` | Pass | `100/100`. |
+| OpenFlow | `node bin/xflow.js compare openspec --json` | Pass | OpenFlow `93`, OpenSpec `73`. |
+| OpenFlow | `node bin/xflow.js compare superpowers --json` | Pass | OpenFlow `91`, Superpowers `78`. |
+| OpenFlow | `node bin/xflow.js compare gstack --json` | Pass | OpenFlow `96`, gstack `80`. |
+| OpenFlow | `npm run drift:scan` | Pass | 9/9 drift checks passed. |
+| OpenFlow | `node --test test/cli-usability.test.js` | Pass | 67/67 tests passed after public-boundary updates. |
+| OpenFlow | `node --test test/competitive-readiness.test.js` | Pass | 16/16 tests passed after public-boundary updates. |
+| OpenFlow | `gitleaks detect --no-git --redact --source .` | Pass | No leaks found in the extracted tree. |
+| gstack | `./setup --host openclaw` | Pass | Safe non-mutating host path prints integration instructions. |
+| gstack | `bun run skill:check` | Fail | Skill command validation mostly passed, but generated host skill freshness failed and `claude/SKILL.md` was missing. |
+| gstack | `bun install --frozen-lockfile` | Inconclusive | No output for an extended wait; killed to avoid blocking the benchmark. |
+| Superpowers | `npm pack --dry-run --json` | Pass | Package dry run succeeded. |
+| Superpowers | `CLAUDE_PLUGIN_ROOT=<repo> bash hooks/session-start` | Pass | Hook produced valid JSON context injection. |
+| OpenSpec | `npm ci` | Pass | Installed 304 packages and built successfully. |
+| OpenSpec | `node bin/openspec.js --help` | Pass | CLI exposed command surface. |
+| OpenSpec | `node bin/openspec.js validate --all --json` | Fail | 49/54 items passed; 5 change proposals lacked spec deltas. |
+| OpenSpec | `npm test` | Pass | 76 test files and 1512 tests passed. |
+
+## Scorecard
+
+| Dimension | Weight | OpenFlow | gstack | Superpowers | OpenSpec |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| First-run / install check | 10 | 9 | 6 | 8 | 9 |
+| Executable workflow state | 15 | 15 | 9 | 8 | 10 |
+| TDD / verification gates | 15 | 14 | 10 | 14 | 9 |
+| Spec durability | 10 | 10 | 7 | 7 | 10 |
+| Repo-local auditability | 15 | 15 | 10 | 9 | 9 |
+| Cross-host portability | 10 | 9 | 9 | 10 | 10 |
+| Release / claim gates | 15 | 13 | 8 | 7 | 8 |
+| Public-boundary hygiene | 10 | 9 | 7 | 8 | 8 |
+| **Total** | **100** | **94** | **66** | **71** | **73** |
+
+## Interpretation
+
+OpenFlow leads this benchmark because it combines a runnable workflow engine,
+machine-checked gates, release checks, handoff continuity, and explicit claim
+boundaries from source checkout.
+
+gstack remains strong for role-rich operator workflows and browser/QA rituals,
+but the tested checkout exposed generated-skill freshness failures.
+
+Superpowers remains the strongest low-ceremony behavior-discipline layer across
+agent hosts, especially for planning, TDD, debugging, and review. It is less of
+a repo-owned execution runtime.
+
+OpenSpec remains strongest for lightweight spec-driven development. Its own test
+suite passed, but repository-wide `validate --all` surfaced five incomplete
+change deltas in the tested checkout.
+
+## Public Claim Boundary
+
+Safe claim: OpenFlow is ahead in this benchmark for repo-owned delivery closure,
+auditability, release gates, and cross-session workflow evidence.
+
+Unsafe claim: OpenFlow universally makes gstack, Superpowers, or OpenSpec
+obsolete. Each tool remains strong in its narrower operating model.

package/docs/compatibility.md

@@ -0,0 +1,52 @@
+# evalid Compatibility Notes
+
+`evalid` is designed to work as a workflow runtime below multiple agent tools. The agent can change, but the project artifacts, workflow YAML, gates, and archive rules stay stable.
+
+For installation snippets by tool, see `docs/tooling-matrix.md`.
+
+## Codex
+
+- Use project-local instructions to call `xflow:takein`, `xflow:plan`, and `xflow:yolo`.
+- Run `xflow doctor` before substantial work in a new checkout.
+- Use `npm run drift:scan` before editing active workflow or skill surfaces.
+
+## Claude Code
+
+- Treat `docs/quickstart.md` as the first-run path.
+- Keep the active plan in `specs/changes/<change-id>/plan.md`.
+- Run `xflow workflow validate yolo` or `xflow workflow validate corps` before executing a workflow.
+
+## Cursor
+
+- Put xflow commands in project rules or agent instructions rather than duplicating workflow prose.
+- Keep `.as-xflow/config.json` in the project root as the local contract.
+- Use `xflow doctor --json` for machine-readable readiness checks.
+- Let `.as-xflow/config.json` carry workflow aliases, issue routing defaults, and skill sync defaults across tools.
+
+## OpenCode
+
+- Prefer CLI commands over editor-specific state: `xflow init`, `xflow doctor`, `xflow workflow validate yolo`.
+- Keep verification in package scripts so OpenCode tasks can run the same checks as Codex or Claude Code.
+
+## Generic CLI Agents
+
+- Required commands are intentionally plain shell commands.
+- Minimum adoption path:
+  - `xflow init --project-root .`
+  - `xflow doctor --project-root .`
+  - `xflow workflow validate yolo`
+  - `npm run drift:scan`
+
+## Gemini CLI
+
+- Use the universal CLI contract from `docs/tooling-matrix.md`.
+- Treat xflow as the workflow source of truth and Gemini as the executor.
+- Validate workflow data with `xflow workflow validate yolo --project-root .` before running implementation.
+
+## Invariants Across Tools
+
+- `xflow:plan` remains track-neutral.
+- `xflow:yolo` and `xflow:corps` reuse a current plan instead of re-planning.
+- `xmem` remains outside the xflow namespace.
+- Archive publish stays owned by `A5.archive.commit_push_close` before `A6.pr.create`.
+- Installed skill sync goes through the evalid wrapper and verifies with `npm run skill:diff`.

package/docs/competitive-benchmark.md

@@ -0,0 +1,108 @@
+# evalid Competitive Benchmark
+
+Date: 2026-04-19
+
+## Goal
+
+Make `evalid` stronger than adjacent agent workflow systems in every dimension that matters for serious delivery work: planning, execution, verification, portability, team handoff, and operator confidence.
+
+This benchmark is intentionally stricter than a marketing comparison. A category is only considered won when `evalid` has a named project surface, a command or artifact operators can use, and local tests or drift scans that protect it.
+
+## Reference Systems
+
+- Superpowers: strong skill distribution, agent behavior shaping, and test-driven coding guidance.
+- Super-Assistant: broad enterprise harness with team constraints, checkpoint notifications, plugin execution, experience indexing, and S3-backed sync.
+- OpenSpec: strong spec-driven workflow, low-friction command surface, and cross-tool positioning.
+- gstack: strong role-specialist command surface, browser QA, and host-native release rituals for Codex / Claude Code.
+- spec-kit: strong specification-driven development lifecycle, broad public extension surface, and ecosystem credibility.
+
+## Score Dimensions
+
+| Dimension | Win Condition | Current evalid Surface | Current Status |
+| --- | --- | --- | --- |
+| Local delivery closure | One command family can move from plan through archive with verification evidence. | `xflow:plan`, `xflow:yolo`, `xflow:corps`, `workflows/*.yaml`, archive atoms | Strong |
+| Goal alignment | Project direction survives across threads, tools, handoffs, and workflow tracks. | `xflow goal set`, `xflow goal audit`, `xflow compare codex-goal`, `xflow:goal`, `.xflow/GOAL.md`, `docs/goal-vs-codex.md`, yolo/corps/Ralph goal-alignment rules | Strong |
+| Executable workflow data | Workflow order is data, validated by schema/tests, not only prose. | `workflows/yolo.yaml`, `workflows/corps.yaml`, `schemas/workflow.schema.json` | Strong |
+| Verification rigor | Drift checks, tests, gates, and sync checks catch regressions before release. | `npm test`, `npm run drift:scan`, `npm run skill:diff`, deterministic gates | Strong |
+| TDD / code quality push | Red runs before implementation, green runs after implementation, and changed tests are checked for quality anti-patterns. | `I6a.tdd.run`, `I6b.tdd.proof_validate`, `I6c.tdd.quality_review`, `test/tdd-proof.test.js`, `verify_proof.json` | Strong |
+| Operator onboarding | First commands explain the human loop, initialize a project, and report whether the local install is ready. | `xflow quickstart`, `xflow guide`, `xflow init`, `xflow doctor`, `npm run doctor` | Strong |
+| One-shot evaluation | External evaluators can see quality score, Codex goal / Superpowers / Super-Assistant positioning, plus OpenSpec / gstack comparisons, launch blockers, release-owner status, claim boundaries, next actions, and first-run path from one command family. | `xflow evaluate`, `xflow evaluate --json`, `xflow release status`, `xflow release status --json`, `xflow compare codex-goal --json`, `xflow compare superpowers --json`, `xflow compare super-assistant --json`, `xflow compare openspec --json`, `xflow compare gstack --json`, `xflow assess --json`, `xflow launch audit --json`, `xflow launch claims --json`, `xflow launch copy --json` | Strong |
+| Spec durability | Plans, proposal artifacts, workflow deltas, AHA, and handoff survive thread changes. | `specs/changes/*`, `specs/workflow.md`, `AHA.md`, `HANDOFF.md` | Strong |
+| Cross-tool portability | Skills and workflows can be installed without personal machine assumptions. | `docs/compatibility.md`, `.as-xflow/config.json`, skillhub sync wrapper, installed skill diff | Strong |
+| Public product clarity | New users can understand the system without reading implementation internals. | README badges, `xflow quickstart`, `xflow guide`, `xflow evaluate`, `xflow assess`, `xflow demo launch`, `xflow launch dossier`, `xflow launch claims`, `xflow launch copy`, `xflow launch audit`, `xflow adoption status`, `xflow adoption trial`, `xflow package status`, `xflow package preflight`, `xflow package audit`, `xflow score`, `docs/quality-assessment.md`, `docs/launch-demo.md`, `docs/examples-gallery.md`, `docs/adoption/README.md`, `docs/methodology.md`, `docs/public-benchmark.md`, `RELEASE_NOTES.md`, `docs/fixtures/tracker-item.json`, this benchmark | Strong |
+| Team collaboration | Issues, branches, PR/archive state, handoff, and reviewer checks are explicit and auditable. | `docs/reviewer-guide.md`, openissue/archive atoms, current-state handoff block | Strong |
+| Control-plane observability | Operators can inspect run state, gates, orphaned runs, and aggregate signals. | `xflow serve`, server tests, timeline analytics | Strong |
+| Ecosystem packaging | External users can install, initialize, upgrade, inspect package readiness, and import external tracker context with minimal manual wiring. | `docs/install-upgrade.md`, `docs/public-release.md`, `docs/demo-proof.md`, `docs/fixtures/tracker-item.json`, `.github/workflows/ci.yml`, `package.json` bin/files, `npm run publish:check`, `xflow adapter import-file`, `xflow adapter github-issue` | Strong |
+
+## Current Judgment
+
+`evalid` now beats reference systems on executable workflow depth, local delivery closure, archive discipline, observable heavy-track control, first-run commands, split red/green TDD proof semantics, TDD test-quality review, deterministic requirements-level spec delta review, OpenSpec migration mapping, public release checks, real adapter seams, examples gallery, public benchmark proof, methodology guidance, and reviewer-facing collaboration guidance.
+
+Against Superpowers, xflow should not claim behavior-guidance superiority.
+Superpowers remains stronger as lightweight behavior discipline; xflow's
+stronger claim is repo-local workflow evidence, cross-tool state, and launch
+gates.
+
+Against Super-Assistant, xflow should not claim broader concrete enterprise
+connector inventory. Super-Assistant remains a useful reference for DingTalk,
+plugin, checkpoint, experience, and S3 patterns. xflow's stronger claim is
+absorbing those patterns as a policy overlay and thin atoms, keeping workflow
+authority in local YAML, gates, and proof artifacts.
+
+Against gstack, xflow should not claim better role choreography or browser
+rituals. The stronger xflow claim is repo-owned workflow truth: checked-in YAML,
+goal alignment, handoff/AHA continuity, and launch gates that can be audited
+from source checkout without assuming a specific host command pack.
+
+Against Codex native goal, xflow wins only at the project layer: Codex goal is
+excellent thread memory, while `.xflow/GOAL.md` becomes stronger when yolo,
+corps, Ralph, handoff, and takein all consume it and report alignment. The
+score dimension above is intentionally product-facing: a public user should be
+able to see why `xflow:goal` is not a duplicate prompt reminder.
+CLI users should be able to prove the same story without knowing the skill
+system first: `xflow goal set` writes the durable anchor, and `xflow goal show
+--json` exposes it to any agent runtime. `xflow goal audit --json` then proves
+the core skill family still consumes the anchor instead of leaving it as a
+decorative file.
+
+The remaining product moat work is no longer the core engine; it is distribution and ecosystem proof. The current repo now includes a root README with public badges, install/upgrade page, tooling matrix, demo proof page, walkthrough, integration matrix, public release gate, release notes, public benchmark, examples gallery, spec-kit benchmark, and CI-backed minimal adoption example so the external story is testable instead of aspirational.
+
+The highest-leverage path is not more workflow phases. The next win is authenticated public registry publish plus third-party adoption data from real teams, recorded through `docs/adoption/README.md`.
+
+## Proof Commands
+
+```bash
+xflow score
+xflow quickstart
+xflow evaluate --json
+xflow assess --json
+xflow demo launch --json
+xflow launch dossier
+xflow launch claims --json
+xflow launch copy --json
+xflow launch audit --strict --json
+xflow adoption kit --name <team-or-project> --source <tracker-or-pr> --track yolo
+xflow adoption init --name <team-or-project> --source <tracker-or-pr> --track yolo
+xflow adoption validate --json
+xflow package preflight --check-registry --check-auth --json
+xflow launch audit --pre-publish --strict --json
+xflow package audit --check-registry --json
+xflow goal show --json
+xflow goal audit --json
+xflow corps --explain --json
+xflow compare codex-goal
+xflow compare gstack
+xflow compare superpowers
+xflow compare super-assistant
+xflow compare openspec
+xflow compare spec-kit
+xflow adapter import-file --input docs/fixtures/tracker-item.json --json
+xflow spec delta --change-id <change-id>
+npm run release:pack
+npm run publish:check
+```
+
+## Required Next Wins
+
+1. Run `npm run publish:check`, confirm package ownership and npm identity with `xflow package preflight --check-registry --check-auth --json`, require `xflow launch audit --pre-publish --strict --json` before the irreversible publish, publish the package to the public registry, and verify it with `xflow package audit --check-registry --json`.
+2. Extend the current non-fixture maintainer adoption record with at least one third-party tracker workflow using `xflow adoption status`, `xflow adoption trial`, `xflow adoption kit`, `xflow adoption init`, and `docs/adoption/README.md`, then gate it with `xflow adoption validate --json`.

package/docs/corps-operator-guide.md

@@ -0,0 +1,75 @@
+# Corps Operator Guide
+
+Use this page when `xflow:corps` feels too large to start. The short version:
+corps is the heavy track for product/UI risk, not a replacement for yolo.
+
+## Verdict
+
+Use corps when the work needs governed product proof:
+
+- new user-facing product surface or interaction pattern
+- competitor-led UI or visual fidelity matters
+- multiple agents should propose, critique, or repair
+- completion must be accepted from artifacts instead of chat summary
+
+Do not use corps for ordinary backend, docs, or infrastructure changes. Use
+`xflow:yolo` for that path.
+
+## First-Time Sequence
+
+```bash
+xflow corps --explain
+xflow goal show --json
+xflow goal audit --json
+xflow corps --title "<product or UI change>" --change-type frontend --change-id <change-id> --dry-run --json
+xflow corps --title "<product or UI change>" --change-type frontend --change-id <change-id>
+xflow proof --track corps --change-id <change-id>
+```
+
+The dry run explains the proof contract. The real run is not complete until
+`xflow proof --track corps` writes `corps_proof.json` with `ok=true`.
+
+## Proof Contract
+
+Corps completion requires all of this:
+
+- `specs/changes/<change-id>/corps_proof.json` reports `ok=true`
+- the built-in governed corps workflow manifest is used
+- hash-linked execution logs contain every canonical phase, atom, and gate
+  witness
+- required product, visual, QA, and archive artifacts exist
+- no `stub`, `task_queued`, or `pencil_stubbed` runtime fallback appears
+- the operator confirms the proof aligns with `.xflow/GOAL.md`
+
+## Competitor-Led UI Inputs
+
+Competitor-led UI requires a primary reference surface and exactly one benchmark
+evidence path before execution:
+
+```bash
+xflow corps \
+  --title "Competitor-aligned workbench" \
+  --change-type frontend \
+  --change-id competitor-workbench \
+  --competitor-product "<name>" \
+  --primary-reference-surface primary_workspace \
+  --capture-url http://127.0.0.1:4174/ \
+  --reference-image refs/competitor-main.png
+```
+
+Use `--reference-scenarios-json <path>` instead of `--capture-url` plus
+`--reference-image` when the benchmark scenarios are already frozen.
+
+## Common Failure Meanings
+
+| Issue | Meaning |
+| --- | --- |
+| `competitor_led_ui_requires_benchmark_input` | The entry detected competitor-led UI but cannot prove visual comparison without benchmark evidence. |
+| `competitor_led_ui_requires_primary_reference_surface` | The entry cannot tell which surface anchors the comparison. |
+| `stub runtime fallback` | A required heavy agent runtime was unavailable or unauthenticated, so completion is not claimable. |
+
+## Human Role
+
+The conversation AI should not manually emulate corps. It represents the human
+operator: clarify requirements, acknowledge human gates when needed, and inspect
+`corps_proof.json` before accepting completion.

package/docs/demo-proof.md

@@ -0,0 +1,126 @@
+# evalid Demo Proof
+
+This page defines what an external evaluator should run before trusting xflow claims.
+
+## Clean Project Adoption
+
+From an empty temporary project:
+
+```bash
+npm install -g @surlymochan/evalid
+xflow demo clean
+xflow guide
+xflow assess
+xflow demo launch
+xflow init --project-root .
+xflow goal set "Ship the next verified change" --project-root .
+xflow goal audit --project-root . --json
+xflow doctor --project-root .
+xflow workflow validate yolo --project-root .
+```
+
+Expected result:
+
+- `.as-xflow/config.json` exists
+- `.xflow/GOAL.md` exists and `xflow goal audit --json` passes
+- doctor exits successfully
+- `yolo` validates through project-local config
+- no internal workflow files need to be copied into the consumer project
+
+The repository CI runs this same path by creating a minimal temporary `package.json` on the fly.
+For source checkout evaluation before npm publication, run `node bin/xflow.js
+demo clean` from this repository; it creates the temporary project, runs the
+same init/goal/doctor/yolo validation smoke, and cleans up automatically.
+
+## Source Checkout Release Proof
+
+From the evalid repository:
+
+```bash
+npm run release:pack
+```
+
+This proves:
+
+- full test suite passes
+- active-surface drift scan passes
+- installed xflow skill matches source
+- package dry-run includes the runtime, docs, workflows, and skills
+- package dry-run excludes local config, test fixtures, Python caches, and Finder metadata
+
+## TDD Proof Demonstration
+
+A real yolo run must produce:
+
+```text
+specs/changes/<change-id>/tdd/red-0.json
+specs/changes/<change-id>/tdd/green-0.json
+specs/changes/<change-id>/tdd/quality-0.json
+```
+
+The required semantics are:
+
+- `red-0.json` records a failing raw test command before implementation
+- `green-0.json` records a passing raw test command after implementation
+- `quality-0.json` rejects code changes without meaningful changed tests
+- quality review rejects empty assertions, snapshot-only tests, and mock-heavy tests without real assertions
+
+## Competitive Claim Gate
+
+Before claiming a new competitive advantage, run:
+
+```bash
+xflow score
+xflow goal audit --json
+xflow corps --explain --json
+xflow compare superpowers
+xflow compare super-assistant
+xflow compare openspec
+xflow compare gstack
+xflow compare spec-kit
+xflow adapter import-file --input docs/fixtures/tracker-item.json --json
+xflow spec delta --change-id <change-id>
+npm run drift:scan
+npm run release:pack
+npm run publish:check
+```
+
+The claim is not durable unless it is backed by:
+
+- a user-facing command
+- a durable doc page
+- workflow or atom evidence where relevant
+- a test that fails if the evidence disappears
+
+## Corps Capture-Url Proof
+
+For competitor-led UI work, the heavy-track benchmark contract now supports two
+formal evidence paths. One of them is the phase-local capture path:
+
+```bash
+xflow corps \
+  --title "Competitor-aligned workbench" \
+  --change-type frontend \
+  --change-id competitor-workbench \
+  --competitor-product CompetitorX \
+  --required-modules workspace \
+  --required-modules detail \
+  --capture-url http://127.0.0.1:4174/ \
+  --reference-image refs/competitor-main.png \
+  --dry-run \
+  --json
+```
+
+What must be true before calling the run complete:
+
+- `H6.visual.benchmark` records `benchmark_input_mode: "capture_url"`
+- `visual_benchmark.json` is `reference_backed`
+- the captured scenario resolves both `reference_image` and `screenshot_image`
+- `xflow proof --track corps --change-id <id>` returns `ok=true`
+
+## Minimal Example
+
+Use the clean project adoption block above as the canonical minimal example.
+Use [docs/launch-demo.md](./launch-demo.md) when the evaluator wants the public
+goal-to-yolo and goal-to-corps proof story instead of only the minimal install
+smoke.