Merge pull request #25 from bx33661/bx3/fix-preflight-issues

feat: Campaign, PatternPacks, provenance, readiness gates + OSS polish

Author: bx33661

.gitignore

@@ -4,16 +4,19 @@
 # Project-scoped Codex installs created by `omv setup --scope project`
 .codex/
 
-# Local assistant/OpenSpec scaffolding and nested worktrees
+# Local assistant scaffolding and nested worktrees
 .agents/
 .claude/
 .github/prompts/
 .github/skills/
-openspec/
-SPEC.md
 oh-my-codex/
 oh-my-claudecode/
 
+# OpenSpec: publish accepted specs; keep in-progress change drafts local
+openspec/changes/
+# Root historical vision draft only (do not match openspec/**/spec.md on case-insensitive FS)
+/SPEC.md
+
 # TypeScript build output
 dist/
 node_modules/

.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:

CODE_OF_CONDUCT.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Security Research Norms
+
+This project is for **passive vulnerability research** and responsible disclosure
+preparation. Community participation also means:
+
+* Do not share live exploit traffic against third-party systems
+* Do not post real private finding evidence, credentials, or unreleased
+  vulnerability details in issues or pull requests
+* Prefer sanitized fixtures and public, already-disclosed examples in demos
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers through the contact options listed in
+[SECURITY.md](SECURITY.md). All complaints will be reviewed and investigated
+promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1,
+available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

CONTRIBUTING.md

@@ -2,6 +2,12 @@
 
 Thanks for helping improve `oh-my-vul`. This project is a Claude Code skill collection, so the most important contribution quality is reproducibility: installed skills, `.skill` archives, and source checkout behavior should all match.
 
+By participating, you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+**Do not commit** local research state (`.omv/`), secrets, live target data, or unreleased vulnerability details. Use sanitized fixtures in issues and pull requests.
+
+Accepted behavior specs live under [`openspec/specs/`](openspec/specs/). In-progress OpenSpec change drafts stay local (`openspec/changes/` is gitignored).
+
 ## Development Setup
 
 ```sh