@surlymochan/evalid 0.0.0-stage → 0.3.1

package/docs/public-release.md

@@ -0,0 +1,145 @@
+# Public Release Gate
+
+This page defines the final public-release boundary for evalid. It is intentionally stricter than local development because distribution is part of the product surface.
+
+## Current Registry Status
+
+The package name `evalid` was checked against the npm public registry during the release-hardening pass and returned `404 Not Found`, meaning no published package with that name was visible at that time.
+
+Do not treat this as permanent ownership. Re-check before publishing.
+
+```bash
+npm view @surlymochan/evalid name version --json
+```
+
+## Release Check
+
+Run:
+
+```bash
+npm run publish:check
+xflow evaluate --json
+xflow release status --json
+xflow launch dossier --output docs/launch-dossier.md
+xflow launch claims --json
+xflow launch copy --json
+xflow adoption trial --name <team-or-project> --source <tracker-or-pr> --track yolo --json
+xflow goal audit --json
+xflow adoption status --json
+xflow package status --json
+xflow package preflight --check-registry --check-auth --json
+xflow launch audit --pre-publish --strict --json
+xflow package audit --check-registry --json
+xflow launch audit --strict
+```
+
+For the exact last-mile command sequence and current auth boundary, use
+[npm Publish Handoff](./npm-publish-handoff.md).
+
+This expands to:
+
+```bash
+npm run release:pack
+npm publish --dry-run --access public
+```
+
+Expected proof:
+
+- full test suite passes
+- active-surface drift scan passes
+- installed xflow skill diff is clean
+- npm package dry-run excludes local config, tests, Python caches, and Finder metadata
+- npm publish dry-run can construct the public package without mutating the registry
+- evaluate gives a single machine-readable brief with score, Codex goal / Superpowers positioning, launch blockers, package evidence, release-owner status, safe claims, and the recommended first-run path
+- launch dossier gives reviewers one concise, audit-backed summary of quality, goal comparison, yolo/corps proof paths, release gate, and blockers
+- launch claims lists public claims that are safe now and claims that must wait for missing evidence
+- launch copy generates announcement text, evaluation commands, and forbidden phrases from the same claim boundary
+- launch audit includes `next_actions` so the release owner can see the exact commands needed to clear missing evidence
+- launch audit embeds package preflight/audit `next_actions` under
+  `package_evidence` so automation can diagnose npm auth or registry blockers
+  without a second CLI call
+- launch audit separates `available_surfaces` from `ready_surfaces` so runnable checks are not mistaken for evidence that has already passed
+- goal audit proves `.xflow/GOAL.md` exists and the core skill family still consumes it before goal superiority claims are published
+- package preflight confirms npm identity and package-name/version availability before the irreversible publish
+- npm publish handoff records the current auth boundary and exact stop conditions
+- pre-publish launch audit confirms the release is ready for the irreversible publish step, while still refusing to hide missing adoption or package proof
+- package audit confirms the public npm registry reports the expected name and version
+- launch audit separates verified engine/adoption/package evidence from missing registry proof
+
+## Authentication Check
+
+The real publish requires an authenticated npm session:
+
+```bash
+npm whoami
+```
+
+If this returns `E401 Unauthorized`, stop at `npm run publish:check`; the package is dry-run ready but cannot be published from this machine until npm auth is restored.
+
+## Actual Publish Boundary
+
+Only run the real publish after the release check is green and version ownership is confirmed.
+
+```bash
+npm publish --access public
+```
+
+## Required Pre-Publish Evidence
+
+Record these in the release note or PR:
+
+- `npm run release:pack`
+- `npm run publish:check`
+- `xflow evaluate --json`
+- `xflow release status --json`
+- `xflow launch dossier --output docs/launch-dossier.md`
+- `xflow launch claims --json`
+- `xflow launch copy --json`
+- `xflow adoption trial --name <team-or-project> --source <tracker-or-pr> --track yolo --json`
+- `xflow goal audit --json`
+- `xflow adoption status --json`
+- `xflow package status --json`
+- `xflow package preflight --check-registry --check-auth --json`
+- `xflow launch audit --pre-publish --strict --json`
+- `xflow adoption validate --json`
+- `xflow adoption validate --splash --json`
+- `xflow package audit --check-registry --json`
+- `xflow launch audit --strict --json`
+- `xflow launch audit --splash --strict --json`
+- `docs/adoption/README.md` reviewed, with at least one real adoption record before splash launch
+- `docs/adoption/openflow-release-hardening.md` reviewed as the current non-fixture adoption record
+- `docs/npm-publish-handoff.md` reviewed before real publish
+- `xflow score`
+- `xflow compare superpowers`
+- `xflow compare super-assistant`
+- `xflow compare openspec`
+- `xflow compare gstack`
+- `xflow compare spec-kit`
+- `docs/team-adoption.md` 95 percent readiness gate reviewed
+- `git status --short --branch`
+
+## Failure Rules
+
+- If `npm view @surlymochan/evalid` returns an existing package not owned by this project, choose a new package name before publishing.
+- If `xflow package preflight --check-registry --check-auth --json` fails, do not run the real publish.
+- If `xflow goal audit --json` fails, do not claim xflow goal is stronger than Codex native goal.
+- If `xflow launch claims --json` lists a claim under `blocked_claims`, do not use that claim in launch copy.
+- If `xflow launch copy --json` lists a phrase under `forbidden_phrases`, do not use that phrase in launch posts, README badges, or release notes.
+- If `xflow launch audit --pre-publish --strict --json` fails, do not run the real publish; strict pre-publish mode runs the same npm identity and registry checks as package preflight, then combines them with score and adoption evidence.
+- If `xflow package audit --check-registry --json` fails after publish, do not claim public package availability.
+- If `npm publish --dry-run` includes `test/`, `.claude/`, `__pycache__`, `.pyc`, or local `.as-xflow/` state, fix package inclusion before publishing.
+- If `xflow score` falls below `100/100`, fix score evidence before publishing.
+- If `xflow launch audit --strict --json` lists `real_external_adoption` as missing,
+  publish can still be dry-run ready, but do not claim an industry-splash
+  launch until a real adoption artifact exists under `docs/adoption/` or a
+  linked public PR provides equivalent evidence. The audit removes this gap
+  only when the adoption validator passes.
+- If `xflow launch audit --splash --strict --json` lists `third_party_adoption`
+  as missing, do not claim broad third-party adoption or industry-splash
+  readiness; maintainer dogfooding can support quality claims, but not ecosystem
+  adoption claims.
+- If `xflow compare spec-kit` points to missing docs, do not publish a superiority claim.
+- If `xflow compare gstack` cannot clearly explain where gstack is stronger, do not publish a fair comparison claim.
+- If `xflow compare superpowers` cannot explain where Superpowers is stronger, do not publish a fair comparison claim.
+- If `xflow compare super-assistant` cannot explain where Super-Assistant keeps stronger enterprise connector breadth, do not publish a fair comparison claim.
+- If the team adoption operating model is not linked from README or reviewer docs, do not promote the package for multi-person adoption.

package/docs/quality-assessment.md

@@ -0,0 +1,139 @@
+# evalid Quality Assessment
+
+Date: 2026-05-23
+
+## Verdict
+
+`evalid` is strong enough to present as a serious open-source agent delivery
+runtime today. The core engine is no longer the weak point: yolo and corps both
+have executable workflow data, verification gates, and release checks.
+
+The remaining gap for an industry splash is distribution proof: publish the
+package and show a polished external demo. Fixture-only adoption proof has been
+replaced with a reviewable maintainer release-hardening record, while broader
+third-party adoption remains the next ecosystem win.
+
+In readiness terms, the current state is:
+
+- `source_checkout`: ready
+- `open_source_launch`: blocked by `published_package`
+- `industry_splash`: blocked by `published_package` and `third_party_adoption`
+
+## Objective Audit
+
+- `goal_vs_codex`: proven at the project layer
+- `yolo_delivery`: proven from source checkout
+- `corps_delivery`: proven from source checkout
+- `skill_family_open_source_credibility`: ready from source checkout
+- `open_source_launch`: blocked by `published_package`
+- `industry_splash`: blocked by `published_package` and `third_party_adoption`
+
+## Can xflow Beat Codex Native Goal?
+
+Yes, but only in a specific way.
+
+Codex native goal is better for one active thread: it is close to the model,
+cheap to update, and useful for completion accounting. `xflow:goal` is better
+for project delivery when `.xflow/GOAL.md` becomes a durable artifact that yolo,
+corps, Ralph, handoff, and takein all read and audit.
+
+That distinction is the product claim:
+
+```text
+Codex goal = thread memory
+xflow goal = project alignment evidence
+```
+
+## Scorecard
+
+| Surface | Grade | Current Evidence | Next Win |
+| --- | --- | --- | --- |
+| `xflow:goal` | A | `.xflow/GOAL.md`, `xflow goal set`, `xflow goal show --json`, `xflow goal audit --json`, `docs/goal-vs-codex.md` | Real examples where goal alignment changed review or handoff quality |
+| `xflow:yolo` | A | YAML workflow, split TDD proof, quality review, archive order, drift tests | Tiny public bugfix demo from red proof to archive |
+| `xflow:corps` | A | Governed corps entry, `xflow corps --explain`, `corps_proof.json`, visual benchmark gates, no-stub witnesses | Real product/UI adoption walkthrough backed by corps proof |
+| Skill family | A- | `xflow quickstart`, `xflow guide`, `xflow assess`, `xflow score`, tooling matrix, skill sync/diff, `docs/adoption/openflow-release-hardening.md` | Public npm publish plus third-party adoption evidence |
+
+## Public Proof Path
+
+```bash
+xflow objective
+xflow objective --json
+xflow assess
+xflow assess --json
+xflow evaluate
+xflow evaluate --json
+xflow compare codex-goal --json
+xflow compare superpowers --json
+xflow compare super-assistant --json
+xflow compare gstack --json
+xflow demo launch
+xflow demo launch --json
+xflow launch dossier
+xflow launch claims --json
+xflow launch copy --json
+xflow launch audit
+xflow launch audit --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 status --json
+xflow adoption validate --json
+xflow adoption validate --splash --json
+xflow package status --json
+xflow package preflight --check-registry --check-auth --json
+xflow launch audit --pre-publish --strict --json
+xflow launch audit --splash --strict --json
+xflow package audit --check-registry --json
+xflow score --json
+xflow goal show --json
+xflow goal audit --json
+xflow corps --explain --json
+npm run drift:scan
+npm run release:pack
+```
+
+`xflow assess` is the human-facing assessment. `xflow score` is the repository
+evidence gate. `release:pack` proves the shipped package includes the current
+docs, CLI, workflows, atoms, and skill sources.
+`docs/npm-publish-handoff.md` is the last-mile publish checklist once npm auth
+is restored.
+
+## Completion Boundary
+
+Internal quality is ready: `xflow score --json` is 100/100, `xflow goal audit
+--json` proves the Codex-goal comparison at the project layer, and
+`npm run release:pack` proves the package contents. The remaining blockers are
+external proof, not hidden engine work:
+
+- `npm_auth_and_publish`: requires release-owner npm auth, preflight, real
+  `npm publish --access public`, and registry audit.
+- `third_party_adoption`: requires a real third-party project or public PR
+  started from `xflow adoption kit`, captured with
+  `docs/adoption/<team-or-project>.md`, and validated by `xflow adoption
+  validate --splash --json`.
+
+`xflow evaluate --json` reports both ordinary launch readiness and stricter
+`splash_launch` readiness, plus ordinary `claims` and stricter `splash_claims`,
+so evaluators can distinguish source-checkout quality, post-publish package
+proof, and broad ecosystem claims.
+
+## Open-Source Launch Bar
+
+Before calling the launch story excellent rather than merely ready:
+
+1. Publish the npm package from the verified tarball only after `xflow package preflight --check-registry --check-auth --json` confirms npm identity and package-name/version availability, and `xflow launch audit --pre-publish --strict --json` confirms score plus adoption evidence are not being bypassed.
+2. Keep `xflow adoption validate --json` green with at least one non-fixture
+   adoption record. The current maintainer release-hardening record proves the
+   gate works and names the remaining npm-publication failure; the next
+   ecosystem upgrade is a third-party project or public PR using
+   `xflow adoption kit` before converting trial results into the same
+   evidence shape.
+3. Keep `docs/launch-demo.md`, `docs/launch-dossier.md`,
+   `docs/corps-operator-guide.md`, and `xflow demo launch` current as the
+   canonical walkthrough for `goal -> yolo` and `goal -> corps proof`, and keep
+   `xflow launch dossier` aligned as the concise public-facing summary.
+4. Make `published_package` disappear from `xflow launch audit --strict --json` only
+   after `xflow package audit --check-registry --json` confirms the npm
+   registry reports the expected package name and version.
+5. Keep the scorecard honest: if any public claim lacks a runnable command,
+   checked artifact, or drift test, downgrade it until evidence exists.

package/docs/quickstart.md

@@ -0,0 +1,156 @@
+# evalid Quickstart
+
+Use this path when you want a project to adopt xflow without reading the implementation first.
+
+## 0. See The Delivery Loop
+
+Use the published package path when `evalid` is available from npm:
+
+```bash
+npm install -g @surlymochan/evalid
+xflow quickstart
+xflow guide
+xflow evaluate
+xflow assess
+xflow demo clean
+xflow demo launch
+xflow launch dossier
+```
+
+Use source checkout mode before npm publication:
+
+```bash
+git clone <repo-url> evalid
+cd evalid
+npm install
+npm run release:pack
+node bin/xflow.js quickstart
+node bin/xflow.js evaluate
+node bin/xflow.js assess
+node bin/xflow.js demo clean
+node bin/xflow.js compare codex-goal
+node bin/xflow.js launch dossier
+```
+
+This shows the human-facing loop and the current quality scorecard for goal,
+yolo, corps, and the overall skill family. The demo command shows the public
+goal-to-yolo and goal-to-corps proof story; the launch audit names any missing
+evidence before public promotion; the launch dossier turns the same evidence
+into a one-page public narrative.
+
+Release-owner checks are deliberately separate from this first-run path:
+
+```bash
+xflow release status --json
+xflow adoption trial --name first-team --source first-tracker --track yolo
+xflow adoption kit --name first-team --source first-tracker --track yolo
+xflow adoption init --name first-team --source first-tracker --track yolo
+xflow adoption status --json
+xflow adoption validate --json
+xflow adoption validate --splash --json
+xflow package status --json
+xflow package preflight --check-registry --check-auth --json
+xflow launch audit --pre-publish --strict --json
+xflow launch audit --splash --strict --json
+xflow package audit --check-registry --json
+```
+
+`xflow adoption status` summarizes ordinary and splash adoption blockers without
+failing the release-owner checklist. `xflow adoption trial` previews the external team's copy-paste command sequence
+and evidence checklist without writing files. `xflow adoption kit` creates a
+shareable trial packet for an external project.
+`xflow adoption init` creates only a draft that must be filled from that real
+trial before `xflow adoption validate --json` can pass. Package preflight blocks
+the irreversible publish when npm identity or package availability is missing;
+`xflow package status --json` summarizes that package state without failing;
+package audit fails until the npm registry reports the expected public package
+name and version. Splash validation is stricter than ordinary adoption
+validation: it requires third-party adoption evidence beyond maintainer
+dogfooding before broad ecosystem claims are allowed.
+
+## 1. Initialize
+
+```bash
+xflow init --project-root .
+xflow goal set "Ship the next verified change" --project-root .
+xflow goal audit --project-root . --json
+```
+
+This writes `.as-xflow/config.json` with portable defaults for workflow paths, skill paths, and issue routing.
+Workflow aliases such as `yolo` and `corps` read this config when `--project-root` points at the initialized project. Issue setup and installed skill sync can also read their defaults from this file.
+The goal command writes `.xflow/GOAL.md`, the project direction anchor consumed by `xflow:goal`, `xflow:yolo`, `xflow:corps`, `xflow:ralph`, `xflow:handoff`, and `xflow:takein`. The audit command fails if the project has no durable goal or if the packaged skill family stops declaring that goal as an intake and proof input.
+
+## 2. Check Readiness
+
+```bash
+xflow doctor --project-root .
+```
+
+Doctor checks package scripts, workflow YAML validity, skill topology, and the project root used by execution.
+
+## 3. Validate The Lite Workflow
+
+```bash
+xflow workflow validate yolo
+```
+
+Use `corps` instead of `yolo` when validating the heavy workflow.
+Validation is preflight only; run the heavy track through `xflow corps` and
+confirm final completion with `xflow proof --track corps`.
+
+## 4. Run A Lite Change
+
+```bash
+xflow workflow run yolo --title "<中文标题>" --change-type backend \
+  --tdd-red-command "npm test -- --grep new-failing-case" \
+  --tdd-green-command "npm test"
+```
+
+For real project work, run this from a branch whose name can derive a `CHANGE_ID`, or pass `--change-id <id>`.
+The red command runs before implementation and must fail. After the execute step, the green command must pass, and xflow writes `quality-0.json` to prove code changes came with meaningful changed tests instead of empty assertions, snapshot-only tests, or mock-heavy smoke.
+
+## 5. Run A Heavy Corps Change
+
+```bash
+xflow serve &
+xflow corps --title "<产品标题>" --change-type frontend --change-id <id>
+xflow proof --track corps --change-id <id>
+```
+
+The conversation AI should not manually emulate `xflow:corps`; it clarifies
+requirements, handles human-gate acknowledgements, and inspects
+`corps_proof.json`. The proof only passes when the built-in corps manifest,
+hash-linked phase/atom/gate witnesses, required artifacts, product contracts,
+and no stubbed runtime fallback all pass together.
+
+## Release Checks
+
+```bash
+npm run drift:scan
+npm run verify
+npm run skill:sync
+npm run skill:diff
+npm run release:pack
+xflow host status --json
+```
+
+Use `npm run release:local` when you intentionally want verification followed by installed skill sync.
+By default, `npm run skill:sync` refreshes `~/.codex/skills`, and falls back to
+`~/.agents/skills` only when the Codex install root does not exist. `xmem`
+follows the same target selection. Set `SKILL_SYNC_TARGET_DIRS` when you want
+an explicit multi-target sync.
+
+For a clean adoption example, use the minimal temporary project flow shown in [docs/demo-proof.md](./demo-proof.md).
+
+Low-friction spec and QA helpers:
+
+```bash
+xflow spec start --title "example change" --change-type backend
+xflow qa capture --url http://127.0.0.1:3000 --platform-profile mobile_h5
+```
+
+## Team Adoption
+
+For a team rollout, use [docs/team-adoption.md](./team-adoption.md) before the
+first shared PR. It defines the operator/reviewer/release-owner roles, required
+CI checks, PR acceptance checklist, and the 95 percent public-promotion gate.

package/docs/reviewer-guide.md

@@ -0,0 +1,43 @@
+# evalid Reviewer Guide
+
+Use this guide when reviewing an xflow-driven change in an issue, PR, or handoff.
+For team rollout policy, pair this with [Team Adoption Operating Model](./team-adoption.md).
+
+## What To Check First
+
+1. `HANDOFF.md` current-state block names the active change, stage, verification state, archive state, and next action.
+2. `specs/changes/<change-id>/proposal.md` and `plan.md` match the PR scope.
+3. `verify_proof.json` or the PR body names the verification commands and outcomes.
+4. TDD proof includes a failing red command before implementation, a passing green/refactor command after implementation, and an `I6c` quality proof.
+5. `AHA.md` records durable lessons when the change exposed a reusable workflow insight.
+6. Archive order keeps publish/commit/push/close in `A5.archive.commit_push_close` before `A6.pr.create`.
+
+## Required Reviewer Questions
+
+- Did the implementation stay inside the frozen proposal and plan?
+- Did the workflow data, docs, and tests move together?
+- Did `I6b.tdd.proof_validate` accept red/green semantics, and did `I6c.tdd.quality_review` reject empty/snapshot-only/mock-heavy tests?
+- Did `npm run drift:scan` pass when active workflow or skill surfaces changed?
+- Did `npm run skill:diff` pass after skill source changes?
+- Is any local-machine assumption documented or moved into `.as-xflow/config.json`?
+- Does the PR identify the operator, implementer, reviewer, and release owner when it is part of a team rollout?
+
+## Accept / Request Changes
+
+Accept when the implementation, workflow artifacts, verification proof, and handoff agree.
+
+Request changes when any of these are true:
+
+- The PR changes workflow behavior without schema or test coverage.
+- The PR changes public skill surfaces without `npm run skill:diff` evidence.
+- The PR adds prose workflow steps without matching workflow YAML or atom registry updates.
+- The PR claims archive completion while local status, issue state, or git history disagrees.
+
+## Reviewer Shortcuts
+
+```bash
+xflow doctor
+xflow score
+npm run drift:scan
+npm run skill:diff
+```

package/docs/spec-kit-benchmark.md

@@ -0,0 +1,73 @@
+# spec-kit Benchmark
+
+This benchmark is the repeatable comparison path for spec-kit-style specification-driven delivery.
+
+## Scenario
+
+Use the same brownfield change in both systems:
+
+> Add a deterministic spec delta review for a project that already has proposal, plan, task checklist, and durable root specs.
+
+## xflow Run
+
+```bash
+xflow init --project-root .
+xflow guide
+xflow workflow validate yolo --project-root .
+xflow spec delta --project-root . --change-id <change-id>
+xflow score
+npm run release:pack
+```
+
+Expected xflow artifacts:
+
+- `specs/changes/<change-id>/proposal.md`
+- `specs/changes/<change-id>/plan.md`
+- `specs/changes/<change-id>/spec_delta_review.json`
+- `specs/changes/<change-id>/spec_delta_review.md`
+- `specs/changes/<change-id>/tdd/red-0.json`
+- `specs/changes/<change-id>/tdd/green-0.json`
+- `specs/changes/<change-id>/tdd/quality-0.json`
+- `HANDOFF.md`
+- `AHA.md`
+
+## spec-kit Run
+
+Use the equivalent spec-kit flow:
+
+```text
+/speckit.constitution
+/speckit.specify
+/speckit.plan
+/speckit.tasks
+/speckit.implement
+/speckit.analyze
+```
+
+Record the generated spec, plan, tasks, implementation evidence, and quality checks.
+
+## Scoring Rubric
+
+| Dimension | xflow Win Condition |
+| --- | --- |
+| Requirements traceability | Requirement-level statements appear in `requirements_delta`. |
+| Executable workflow | Workflow order validates from YAML and atom registry. |
+| TDD semantics | Red fails before implementation; green passes after implementation. |
+| Test quality | `quality-0.json` rejects empty, snapshot-only, or mock-heavy tests without assertions. |
+| Archive closure | Handoff/AHA/archive order is explicit and test-covered. |
+| Release readiness | `npm run release:pack` passes. |
+| Public comparison | `xflow compare spec-kit --json` prints machine-readable edges. |
+
+## Current Judgment
+
+xflow should win the local engineering rigor section. spec-kit may still win public ecosystem breadth until xflow has public registry release, richer external adapters, and a larger example library.
+
+Do not claim a full spec-kit product win unless:
+
+- `npm run publish:check` passes
+- `xflow package preflight --check-registry --check-auth --json` passes before public publish
+- `xflow launch audit --pre-publish --strict --json` passes before the irreversible publish step
+- `xflow package audit --check-registry --json` passes after public publish
+- `docs/integrations.md` covers the target integration class
+- `xflow compare spec-kit --json` is green
+- the benchmark artifacts above are produced for the same change

package/docs/super-assistant-comparison.md

@@ -0,0 +1,106 @@
+# Super-Assistant Comparison
+
+Use this page when someone asks whether evalid should absorb Super-Assistant's
+enterprise delivery harness or split separate personal/team workflows.
+
+## Verdict
+
+Super-Assistant has useful enterprise ingredients: team constraints, checkpoint
+notifications, plugin execution, an experience index, and S3-backed team sync.
+Those ideas are worth absorbing.
+
+evalid should not absorb the whole harness. After the policy-overlay
+integration, xflow is stronger because the same capabilities are expressed as
+thin atoms, provider seams, and structured proof artifacts on top of the
+existing `yolo` and `corps` tracks.
+
+```text
+Super-Assistant = enterprise harness and connector inventory
+xflow = workflow runtime plus policy overlay and atomized proof
+```
+
+## Scorecard
+
+Overall, xflow wins the productized workflow comparison: `95/100` versus
+`76/100`. Super-Assistant still has broader concrete enterprise connector
+coverage, but xflow now has the cleaner runtime contract.
+
+| Dimension | Weight | Super-Assistant | xflow | Winner |
+| --- | ---: | ---: | ---: | --- |
+| Workflow runtime authority | 15 | 10 | 15 | xflow |
+| Policy overlay and team constraints | 15 | 12 | 15 | xflow |
+| Adaptive intake | 10 | 8 | 10 | xflow |
+| Enterprise atomization | 15 | 11 | 14 | xflow |
+| Notification / gate separation | 10 | 6 | 10 | xflow |
+| Experience reuse | 10 | 8 | 9 | xflow |
+| Verification and packaging | 15 | 9 | 14 | xflow |
+| Portability and secret boundary | 10 | 5 | 8 | xflow |
+
+Machine-readable form:
+
+```bash
+xflow compare super-assistant --json
+```
+
+## What xflow Absorbed
+
+- `team_constraints.py` becomes `.xflow/profile.json`,
+  `.xflow/team-policy.json`, and `policy_effective.json`. Numeric thresholds
+  take the stricter value, lists merge and dedupe, and team strings/booleans
+  override personal defaults.
+- Demand profiling becomes `workflow_recommendation.json`, generated by
+  `xflow intake recommend`, and remains advisory input rather than a workflow
+  bypass.
+- Checkpoint notification becomes `notify.checkpoint`, which writes
+  `notification/checkpoint-*.json` and explicitly records
+  `approves_gate=false`.
+- Plugin, storage, and experience reuse become `plugin.run`, `storage.sync`,
+  and `experience.digest`. The first provider set is `file`/`mock`/dry-run
+  safe, so DingTalk/S3-style secrets stay outside the core.
+- Team enforcement becomes `policy.gate`, which emits structured
+  `failed_checks` for coverage, reviewer, smoke, and review-artifact
+  requirements.
+
+## Why Not Fork Team Workflows
+
+Do not create `team-yolo` or `personal-yolo`. That would duplicate workflow
+YAML and drift as soon as a phase changes.
+
+The better split is execution mode:
+
+- `personal`: default, local-first, no external providers required.
+- `team`: loads the team policy, enables optional notification/experience
+  atoms, and checks stricter gates.
+
+The workflow authority stays with `workflows/yolo.yaml`,
+`workflows/corps.yaml`, the atom registry, and proof artifacts. External
+systems may inform the run, but they do not advance state by themselves.
+
+## Proof Commands
+
+```bash
+xflow compare super-assistant --json
+xflow profile show --json
+xflow policy validate --json
+xflow intake recommend --change-id team-api-feature --title "team API feature" --description "touches API DB user data and CI" --repo-count 2 --json
+xflow workflow validate yolo
+xflow workflow validate corps
+npm run verify
+npm run drift:scan
+```
+
+For the reference checkout, run Super-Assistant's own validation commands and
+compare the resulting evidence:
+
+```bash
+npm run check
+python3 -m unittest discover -s tests -p 'test*.py' -v
+python3 -m unittest discover -s .harness -p 'test*.py' -v
+```
+
+## Boundary
+
+xflow should keep Super-Assistant's domain lessons, not its coupling model.
+Concrete enterprise providers can be added later, but the first-class contract
+must remain: notification is not approval, plugins are not workflow state, and
+experience is advisory context rather than a gate substitute.