feat: campaign workflow, pattern packs, provenance, and readiness gates

Ship the Unreleased v0.10 foundation without bumping the published version:

- Campaign.v1 with omv first/campaign init|list|show|seed (candidate-only seed)
- SourceRef.v1 and report provenance manifests for artifact integrity
- 14 PatternPack manifests, R/Lua registries, and omv eval runner
- Preflight hygiene: private .omv/ gitignore, clean npm pack, dashboard renderer
- Shared report-readiness helpers (isReportReady) used by doctor/review
- Maintainer docs aligned; keep local research state and OpenSpec scaffolding out of git

Author: bx33661

.npmignore

@@ -0,0 +1,5 @@
+**/__pycache__/**
+**/*.pyc
+**/*.pyd
+**/*.pyo
+**/test_*.py

AGENTS.md

@@ -9,68 +9,44 @@ The project ships a TypeScript CLI (`omv`) for installing skills, plus Markdown
 ```
 src/
   cli/
-    omv.ts                        — CLI entry point (setup / doctor / findings / help)
-    setup.ts                      — copies installable skills to ~/.claude/skills/ or ./.claude/skills/
-    doctor.ts                     — checks installation health
-    findings.ts                   — creates, lists, validates, and promotes Evidence.v1 handoffs
-    paths.ts                      — path utilities (claudeSkillsDir, projectSkillsDir, findingsDir, packageRoot, …)
+    omv.ts                        — thin CLI entry (dispatches to commands/)
+    commands/                     — one module per top-level command (findings, campaign, review, …)
+    findings.ts                   — Evidence.v1 parse / validate / score / doctor / archive
+    workflow.ts                   — shared readiness + next-action policy
+    review.ts                     — report-readiness verdicts (ready | needs-*)
+    campaign.ts                   — Campaign.v1 first-mile research plans
+    setup.ts / doctor.ts          — install skills+agents; health checks
+    paths.ts                      — claudeSkillsDir, findingsDir, packageRoot, …
   index.ts                        — package exports
 
-skills/
-  omv/SKILL.md                  — collection manager (/omv)
-  omv-find/SKILL.md             — find and rank audit targets (/omv-find)
-  omv-find/references/
-    scoring.md                  — scoring rubric, confidence adjustments, filtering, LOC estimation
-    output-contract.md          — final table contract, audit tips, invalid-request template
-  omv-find/scripts/check_output.py  — heuristic eval checker
-  omv-find/evals/evals.json     — behavior-focused eval scenarios
-  omv-find/evals/golden/        — stable golden outputs
-  omv-report/SKILL.md           — generate VulDB/CVE/GHSA/OSV reports (/omv-report)
-  omv-report/references/
-    ecosystems.md               — vendor/product/version rules, CWE mapping, duplicate-CVE databases
-    report-templates.md         — VulDB, GHSA, OSV JSON, Markdown advisory templates
-    examples/                   — filled advisory examples
-  omv-report/scripts/check_output.py  — heuristic eval checker
-  omv-report/evals/evals.json   — behavior-focused report-generation eval scenarios
-  omv-report/evals/golden/      — stable golden outputs
+skills/                           — 9 installable skills (self-contained after setup)
+  omv, omv-find, omv-audit, omv-repro, omv-report,
+  omv-radar, omv-dedup, omv-disclose, omv-critic
 
 shared/
-  references/
-    ecosystems.md               — ecosystem registry sources, GitHub search shapes, flagship exclusions
-    vuln-patterns.md            — vulnerability aliases and source -> sink -> guard patterns
-    cvss-builder.md             — CVSS v3.1 metric decision table and common vectors
-  scripts/
-    collect_metadata.py         — collects GitHub and selected registry metadata as JSON
-    estimate_loc.sh             — estimates source LOC from a GitHub URL or local checkout
+  references/                     — ecosystems, vuln-patterns, cvss-builder, per-eco patterns/
+  pattern-packs/                  — 14 PatternPack.v1 JSON manifests
+  scripts/                        — collect_metadata, estimate_loc, run_evals, …
 
 contracts/
-  evidence.v1.yaml              — finding object: the typed boundary between omv-find and omv-report
-  candidate-list.v1.yaml        — candidate table entry schema produced by omv-find
-  threat-map.v1.yaml            — dataflow threat map schema (planned: omv-audit M2+)
-
-agents/
-  vuln-scanner.md               — passive candidate discovery
-  dataflow-tracer.md             — source -> sink -> guard analysis
-  cvss-analyst.md                — CVSS v3.1 computation
-  dedup-analyst.md               — duplicate CVE/GHSA search
-  report-writer.md               — platform-specific advisory rendering
-  guard-checker.md              — adversarial guard bypass assessment
-  verifier.md                   — adversarial conclusion refutation
-
-.claude/agents/                — Claude Code project subagent registration (auto-discovered)
-  <name>.md                      — frontmatter (name, description, tools, model) + system prompt body
-  Each subagent's body references the matching agents/*.md domain spec. See
-  docs/architecture/agent-team-upgrade.md for the orchestration design.
+  evidence.v1.yaml                — finding object (find → report boundary)
+  candidate-list.v1.yaml          — omv-find table entries
+  threat-map.v1.yaml              — source → transform → sink graph (omv-audit sidecar)
+  verification.v1.yaml            — adversarial verifier review sidecar
+  campaign.v1.yaml                — research campaign plan + seed lanes
+  source-ref.v1.yaml / report-provenance.v1.yaml / submission.v1.yaml
+
+agents/                           — Claude Code subagent specs (installed by omv setup)
+  vuln-scanner, dataflow-tracer, guard-checker, cvss-analyst,
+  dedup-analyst, report-writer, verifier
 
 scripts/
-  sync_metadata.py              — sync package, registry, and README metadata
-  sync_skill_assets.py           — sync canonical shared/contract assets into self-contained skill dirs
-  validate_skill.py             — validates all skill directories and optional .skill packages
-  package_skill.sh              — builds a .skill archive from a skill directory
-  release_check.py              — release-time validator, package builder, SHA-256 manifest printer
-
-registry.yaml                   — collection metadata: versions, produces/consumes bindings
-.github/workflows/validate.yml  — CI validation, packaging checks, stable golden evals
+  sync_metadata.py / sync_skill_assets.py / validate_skill.py
+  package_skill.sh / release_check.py / pattern_packs.py
+
+registry.yaml                     — skills, agents, contracts, versions
+openspec/                         — accepted specs + change archive
+.github/workflows/validate.yml
 ```
 
 ## CLI
@@ -86,13 +62,30 @@ npx oh-my-vul setup --dry-run    # preview only
 omv doctor
 omv doctor --json
 
+# Workspace + campaign
+omv dashboard
+omv first --target <name> --ecosystem npm --vuln traversal --no-interactive
+omv campaign list|show|seed <id>
+omv review <id> --strict
+
 # Manage project-local Evidence.v1 findings
 omv findings list
 omv findings init <id>
 omv findings init <id> --status candidate|confirmed|blocked --force
 omv findings validate
 omv findings validate <id|path>
 omv findings promote <id|path> --status candidate|confirmed|blocked
+omv findings workflow
+omv findings doctor <id>
+omv findings archive <id> --reason blocked|reported
+
+# Sidecars and release gates
+omv threat-map init|validate <id>
+omv verification init|validate <id>
+omv sources init|validate <id>
+omv report artifacts|provenance <id>
+omv repro init <id>
+omv eval --json
 ```
 
 Build the CLI:

CHANGELOG.md

@@ -2,7 +2,15 @@
 
 ## Unreleased
 
-- Richer ThreatMap.v1 rendering: `omv findings show` now displays the full `source → transforms → sink` dataflow per path with per-path confidence, bypassable guards, and a summary line. Previously the renderer collapsed each path to a single `[source] -> [sink]` line, discarding transforms, confidence, and the summary block that the producer now writes.
+### Planned for v0.10.0 — Campaign + evidence graph (draft)
+
+Ship when release notes and `registry.yaml` / `package.json` versions are bumped together.
+
+- **Campaign.v1 first-mile planning** — `omv campaign init|list|show|seed` and the `omv first` alias. Seeding creates conservative candidate Evidence only and never overwrites existing findings or creates proof artifacts.
+- **SourceRef.v1 + report provenance** — `omv sources init|show|validate` and `omv report provenance` manifests that hash Evidence, reports, and available local dependencies. Missing manifests warn; stale confirmed manifests fail artifact checks.
+- **PatternPack.v1 + unified evals** — 14 JSON pattern-pack manifests (including R/Lua), manifest-driven find/audit asset sync, and `omv eval` with human/JSON/JUnit output.
+- **ThreatMap rich render** — `omv findings show` prints full `source → transforms → sink` paths with confidence, bypassable guards, and summary (no longer collapses to a single source→sink line).
+- **Readiness policy helpers** — `isReportReady` / `isSubmissionScoreReady` / `resolveDoctorNextAction` in `workflow.ts` as the shared report-readiness gate used by doctor and review; maintainer docs (`AGENTS.md`, `CLAUDE.md`, `SPEC.md` banner) aligned with the current tree.
 
 ## v0.9.0 - CLI command split and local findings dedup
 

CLAUDE.md

@@ -7,72 +7,32 @@ The project ships a TypeScript CLI (`omv`) for installing skills, plus Markdown
 ## Structure
 
 ```
-src/
-  cli/
-    omv.ts                        — CLI entry point (setup / doctor / help)
-    setup.ts                      — copies skills/ to ~/.claude/skills/
-    doctor.ts                     — checks installation health
-    paths.ts                      — path utilities (claudeSkillsDir, packageRoot, …)
-  index.ts                        — package exports
-
-skills/
-  omv/SKILL.md                  — collection manager (/omv)
-  omv-find/SKILL.md             — find and rank audit targets (/omv-find)
-  omv-find/references/
-    scoring.md                  — scoring rubric, confidence adjustments, filtering, LOC estimation
-    output-contract.md          — final table contract, audit tips, invalid-request template
-  omv-find/scripts/check_output.py  — heuristic eval checker
-  omv-find/evals/evals.json     — behavior-focused eval scenarios
-  omv-find/evals/golden/        — stable golden outputs
-  omv-report/SKILL.md           — generate VulDB/CVE/GHSA/OSV reports (/omv-report)
-  omv-report/references/
-    ecosystems.md               — vendor/product/version rules, CWE mapping, duplicate-CVE databases
-    report-templates.md         — VulDB, GHSA, OSV JSON, Markdown advisory templates
-    examples/                   — filled advisory examples
-  omv-report/scripts/check_output.py  — heuristic eval checker
-  omv-report/evals/evals.json   — behavior-focused report-generation eval scenarios
-  omv-report/evals/golden/      — stable golden outputs
-
-shared/
-  references/
-    ecosystems.md               — ecosystem registry sources, GitHub search shapes, flagship exclusions
-    vuln-patterns.md            — vulnerability aliases and source -> sink -> guard patterns
-    cvss-builder.md             — CVSS v3.1 metric decision table and common vectors
-  scripts/
-    collect_metadata.py         — collects GitHub and selected registry metadata as JSON
-    estimate_loc.sh             — estimates source LOC from a GitHub URL or local checkout
-
-contracts/
-  evidence.v1.yaml              — finding object: the typed boundary between omv-find and omv-report
-  candidate-list.v1.yaml        — candidate table entry schema produced by omv-find
-  threat-map.v1.yaml            — dataflow threat map schema (planned: omv-audit M2+)
-
-agents/
-  vuln-scanner.md               — passive candidate discovery
-  dataflow-tracer.md            — source -> sink -> guard analysis
-  cvss-analyst.md               — CVSS v3.1 computation
-  dedup-analyst.md              — duplicate CVE/GHSA search
-  report-writer.md              — platform-specific advisory rendering
-
-scripts/
-  validate_skill.py             — validates all skill directories and optional .skill packages
-  package_skill.sh              — builds a .skill archive from a skill directory
-  release_check.py              — release-time validator, package builder, SHA-256 manifest printer
-
-registry.yaml                   — collection metadata: versions, produces/consumes bindings
-.github/workflows/validate.yml  — CI validation, packaging checks, stable golden evals
+src/cli/          — TypeScript CLI (commands/ split; findings/workflow/review/campaign domain modules)
+skills/           — 9 omv-* skills (find, audit, repro, report, radar, dedup, disclose, critic, manager)
+shared/           — references, pattern-packs, eval runner helpers
+contracts/        — Evidence, ThreatMap, Verification, Campaign, SourceRef, Submission, …
+agents/           — subagent specs installed to ~/.claude/agents/ by omv setup
+openspec/         — accepted specs + change archive
+registry.yaml     — versions and produces/consumes bindings
 ```
 
+Canonical maintainer map: see `AGENTS.md` (kept in sync with the current tree). Early vision draft `SPEC.md` is historical only.
+
 ## CLI
 
 ```sh
-# Install skills to ~/.claude/skills/
+# Install skills + agents
 npx oh-my-vul setup
-npx oh-my-vul setup --force      # overwrite existing
-npx oh-my-vul setup --dry-run    # preview only
+npx oh-my-vul setup --scope project
+npx oh-my-vul setup --force
+npx oh-my-vul setup --dry-run
 
-# Check installation health
+# Health and workspace
 omv doctor
+omv doctor --strict
+omv dashboard
+omv review <id> --strict
+omv findings workflow
 ```
 
 Build the CLI:

DEVELOPMENT.md

@@ -190,21 +190,62 @@ Tradeoff:
 
 The ledger is intentionally lightweight YAML, not a database or platform. That keeps the project easy to install and review, but it means deeper validation and rendering still need future deterministic helpers.
 
+### Current iteration - Manifest-driven PatternPacks and evals
+
+What changed:
+
+- Added one PatternPack.v1 JSON manifest for every supported ecosystem, including R and Lua.
+- Made manifests drive skill-local pattern distribution and release-time methodology checks.
+- Added one stable eval manifest plus a human/JSON/JUnit Python runner and `omv eval` CLI adapter.
+
+Core idea:
+
+Repeated asset and eval lists are contracts disguised as source code. Moving membership into validated JSON keeps progressive disclosure, package self-containment, local CI, and release checks aligned without rewriting skill-specific assertions.
+
+Tradeoff:
+
+The unified runner still starts one Python process per checker. The suite is small, and preserving each Skill's domain-specific checker is more valuable than premature shared assertion abstractions.
+
 ## Current Weaknesses
 
 - The Evidence.v1 contract is copied into runtime skill directories; drift is checked by `scripts/sync_skill_assets.py --check`, but the duplication still adds release-surface noise.
 - `omv-find` can guide Evidence.v1 handoff creation, but candidate discovery quality still depends on model discipline, source inspection, and available metadata.
 - `omv-report` consumes validation guidance, but advisory rendering is still primarily model-written rather than deterministic.
 - Examples are partly synthetic.
-- Package archives are tracked but not independently diffable.
-- The README is user-facing; keep maintainer workflow details in `CONTRIBUTING.md`, `RELEASE.md`, and this file.
+- Subagent orchestration is documented and installable, but still optional prose-driven rather than a forced fan-out runtime (see `docs/architecture/agent-team-upgrade.md`).
+- Active skills (`omv-radar`, `omv-dedup`, `omv-disclose`, `omv-critic`) have thinner golden coverage than find/audit/repro/report.
+- `src/cli/findings.ts` remains a large domain module (validate + score + doctor + archive).
+- Historical `SPEC.md` listed skills that never shipped; treat OpenSpec + `registry.yaml` as truth.
 
 ## Proposed Next Iterations
 
-### v0.8 - Real Workflow Walkthrough
+### v0.10 - Campaign + evidence graph (in flight / Unreleased)
+
+Goal:
+
+Make the first-mile campaign story and evidence-graph sidecars a coherent release:
+
+- `omv first` / Campaign.v1 seed → candidate queue
+- ThreatMap + Verification + SourceRef + provenance on the report path
+- `omv review --strict` as the pre-report gate in user docs
+- Ship Unreleased items as `v0.10.0`
+
+### v0.11 - Deterministic report compiler
 
 Goal:
 
+Evidence.v1 → structured advisory IR → VulDB/GHSA/OSV/Markdown via CLI render, with LLM only polishing narrative paragraphs.
+
+### v0.12 - Agent team runtime minimum
+
+Goal:
+
+Tighten subagent tools (no unrestricted Bash), default omv-audit orchestration stages, and strict Verification requirements before confirmed/report-ready.
+
+### Earlier: Real Workflow Walkthrough (delivered in docs/examples)
+
+Goal (historical):
+
 Add a sanitized end-to-end example that demonstrates the intended user path:
 
 - run `/omv-find` for a realistic candidate;

README.md

@@ -32,6 +32,12 @@ npx oh-my-vul setup --scope project
 ## Fast Workflow
 
 ```text
+omv first --target acme --ecosystem npm --vuln traversal,auth --no-interactive
+  -> .omv/campaigns/acme.yaml + deterministic runbook
+
+omv campaign seed acme
+  -> candidate Evidence.v1 hypotheses only
+
 /omv-find --lang npm --vuln traversal --count 10
   -> choose a candidate
 
@@ -47,6 +53,9 @@ omv review <id> --strict
 
 /omv-report <id>
 /omv-critic <id>
+omv sources init <id>
+omv report provenance <id>
+omv report artifacts <id>
 omv submissions record <id> --platform vuldb --submission-id 12345 --url https://example.test/submission/12345
 omv findings archive <id> --reason reported
 ```
@@ -57,12 +66,17 @@ Use `omv dashboard` or `/omv next` whenever you are unsure what to do next.
 
 ```sh
 omv dashboard
+omv campaign list
+omv campaign show <id>
 omv findings workflow
 omv findings show <id>
 omv findings validate <id>
 omv review <id> --strict
+omv sources validate <id>
+omv report provenance <id>
 omv report artifacts <id>
 omv submissions track <id>
+omv eval --json
 ```
 
 Useful setup and health checks:
@@ -71,14 +85,15 @@ Useful setup and health checks:
 omv doctor --strict
 omv request preflight
 omv version --json
+omv eval --junit
 ```
 
 ## Skills
 
 <!-- omv:skills:start -->
 | Skill | Command | Category | Purpose |
 |---|---|---|---|
-| `omv` | `/omv` | manager | Local-first project manager — shows workspace status, active finding next actions, archive state, and installed skills |
+| `omv` | `/omv` | manager | Local-first project manager — creates research campaigns, shows workspace status, and delegates finding lifecycle actions |
 | `omv-find` | `/omv-find` | research | Find and rank open-source packages worth auditing for passive CVE research |
 | `omv-audit` | `/omv-audit` | audit | Deep-audit a candidate finding — prove or disprove the vulnerability, fill Evidence.v1 fields for omv-report |
 | `omv-repro` | `/omv-repro` | audit | Guide local reproduction of a finding — walk through execution, record observed_result, confirm or block |
@@ -116,11 +131,14 @@ Project state lives under `.omv/` and is private by default.
 
 | Path | Purpose |
 |---|---|
+| `.omv/campaigns/<id>.yaml` | Campaign.v1 target, scope, priorities, and lanes |
+| `.omv/campaigns/<id>.md` | deterministic campaign runbook |
 | `.omv/findings/<id>.yaml` | Evidence.v1 finding ledger |
+| `.omv/sources/<id>.yaml` | SourceRef.v1 local source identity and Evidence hash |
 | `.omv/threatmaps/<id>.yaml` | ThreatMap.v1 source -> sink -> guard graph |
 | `.omv/verifications/<id>.yaml` | Verification.v1 adversarial review result |
 | `.omv/repro/<id>/` | local reproduction notes and artifacts |
-| `.omv/reports/<id>/` | generated report drafts |
+| `.omv/reports/<id>/` | generated report drafts and `provenance.json` input hashes |
 | `.omv/submissions/<id>.yaml` | submission tracking |
 
 Create or inspect findings: