# Phase 2 Review (v0.1.0-beta)

**Date**: 2026-01-21
**Reviewed state**: `main` @ `826ea41` + current working tree (uncommitted Phase 2 changes)
**Scope**: Phase 2 deliverables in `docs/PLAN-claude-phase2.md` and `docs/IMPLEMENTATION.md` (CLI expansion + plugin wiring + wrapper scripts + tests).

**Status**: All issues resolved. Ready for v0.1.0-beta tag.

## Summary

Phase 2 is largely in place: `scripts/db.py` has the expanded nested CLI, `plugin/scripts/*.sh` wrappers exist, `plugin/.claude-plugin/plugin.json` registers the new flagship commands (`/check`, `/realitycheck`), and docs (`README.md`, `docs/PLUGIN.md`, `docs/IMPLEMENTATION.md`) have been updated to reflect the plugin+CLI direction.

Before tagging `v0.1.0-beta`, the remaining issues are mostly **interface alignment** (docs/flags/config schema) and **test brittleness** (embeddings being generated by default in CLI tests).

## What's Solid

- **CLI shape matches the Phase 2 plan**: `rc-db claim|source|chain|prediction|related|import` exists and is consistent with the nested-subparser approach described in `docs/PLAN-claude-phase2.md`.
- **Plugin manifest is updated**: `plugin/.claude-plugin/plugin.json` includes `/check` and `/realitycheck` alongside the existing commands.
- **Wrappers support multiple install modes**: `plugin/scripts/run-*.sh` resolve framework repo vs installed `rc-*` commands vs bundled `plugin/lib/` (future).
- **Docs are moving toward "true interface"**: `README.md` and `docs/PLUGIN.md` now describe the flagship workflow and wrapper-based invocation.

## Key Gaps / Risks (Prioritized)

### P0: CLI tests likely require embeddings/network by default

The new CLI tests in `tests/test_db.py` call `scripts/db.py claim add` / `source add` / `chain add` without `--no-embedding`. In `scripts/db.py`, embedding generation is the default behavior for these commands. This means `REALITYCHECK_EMBED_SKIP=1 uv run pytest` can still end up trying to download/load a sentence-transformers model (brittle in clean CI/offline environments).

**Recommendation** (pick one):
- Add `--no-embedding` in CLI tests everywhere an `add`/`import` command is invoked, or
- Teach `scripts/db.py` to treat `REALITYCHECK_EMBED_SKIP=1` as "force `--no-embedding`".

**Acceptance criteria**: `REALITYCHECK_EMBED_SKIP=1 uv run pytest -v` passes on a machine with no embedding model cached and no network.

**Resolution**: Added `should_generate_embedding()` helper function that respects `REALITYCHECK_EMBED_SKIP=1` environment variable. All CLI handlers now use this helper instead of directly checking `args.no_embedding`.

### P0: `.realitycheck.yaml` schema drift (PLAN vs implementation)

Implementation now uses a top-level `db_path` key (see `scripts/db.py init-project`, `plugin/scripts/resolve-project.sh`, and `README.md`), while `docs/PLAN-separation.md` still specifies `database.path`.

**Recommendation**:
- Either update `docs/PLAN-separation.md` to adopt `db_path`, or
- Support both (`db_path` and `database.path`) in `resolve-project.sh` and document precedence.

**Acceptance criteria**: all docs agree on the config schema (and examples match the parsing logic).

**Resolution**: Updated all 4 occurrences in `docs/PLAN-separation.md` to use `db_path` and `framework_path` instead of nested `database.path` and `framework.path`. Shell script parsing logic also updated.

### P1: Validation CLI docs and wrapper usage are out of sync

`plugin/commands/validate.md` (and `plugin/scripts/run-validate.sh` comments) document `--yaml PATH`, but `scripts/validate.py` actually supports `--mode yaml --repo-root PATH`.

**Recommendation**:
- Update plugin/docs to the implemented flags, or
- Add a `--yaml` alias to `scripts/validate.py` if you prefer the simpler UX.

**Resolution**: Updated `plugin/commands/validate.md` to document the correct flags: `--mode {db,yaml}`, `--db-path PATH`, `--repo-root PATH`. Added example showing YAML mode usage.

### P1: Chain credence default is inconsistent with help text

In `scripts/db.py`, `chain add` help says "defaults to MIN of claims", but the implementation uses `0.5` when `--credence` is omitted.

**Recommendation**:
- If MIN is intended: compute MIN(claim credences) at add time (or omit `credence` and let DB validation compute/flag), or
- If `0.5` is intended: update CLI help + docs to match and ensure validation rules are consistent.

**Resolution**: Fixed code to actually compute MIN of claims when `--credence` not specified. Looks up each claim in the database and takes the minimum credence value. Falls back to 0.5 only if no claims have credence values.

### P1: `docs/WORKFLOWS.md` still documents the v0.1.0-alpha CLI surface

`docs/WORKFLOWS.md` currently lists `rc-db init|stats|reset|search` only. With Phase 2, this doc is now misleading (and likely to be the first place a new contributor looks).

**Recommendation**: update the "Current CLI Commands" table and at least one end-to-end workflow example to reflect the new nested commands (claim/source CRUD, import, related).

**Resolution**: Complete rewrite of `docs/WORKFLOWS.md` with:
- Updated CLI Commands table (v0.1.0-beta)
- Project Setup section with `init-project`
- Full Claim/Source/Chain/Prediction workflow sections
- Search, Import, Validation, Export, Migration workflows
- Claude Code Plugin section with `/check` workflow
- Environment variables reference

### P2: Wrapper fallback references likely-nonexistent Python modules

`plugin/scripts/run-db.sh` / `run-export.sh` / `run-validate.sh` include fallbacks like `python -m realitycheck.db`, but the current wheel packaging exports the `scripts` package (console scripts exist: `rc-db`, `rc-export`, `rc-validate`).

**Recommendation**: either remove those `python -m realitycheck.*` branches (rely on `rc-*`), or align them with the actual module path you intend to ship.

**Resolution**: Removed the non-working `python -m realitycheck.*` fallback from all three wrapper scripts. The `rc-*` entry points are the correct way to invoke installed packages.

### P2: `/check` is described as "full automation" but is mostly a manual workflow prompt

`docs/PLUGIN.md` describes "Full workflow automation", but `plugin/commands/check.md` currently reads primarily as a checklist/template and does not declare tool permissions (e.g., `WebFetch`, wrapper `Bash(...)`) the way `search`/`export`/`validate` do.

**Recommendation**: decide which you want for v0.1.0-beta:
- **Workflow prompt** (fine): adjust docs phrasing to "guided workflow" and keep it manual, or
- **Automation**: add explicit allowed-tools + a more deterministic execution recipe (including when to run wrappers vs when to ask the user).

**Resolution**: Added `allowed-tools` directive to `/check` command:
```yaml
allowed-tools: ["WebFetch", "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/run-db.sh *)", "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/run-validate.sh *)"]
```

## Beta Tag Checklist

- [x] `REALITYCHECK_EMBED_SKIP=1 uv run pytest -v` passes without cached models
- [x] `.realitycheck.yaml` schema unified across `docs/PLAN-separation.md`, `README.md`, `init-project`, and `resolve-project.sh`
- [x] Validation flags aligned between `scripts/validate.py` and plugin/docs
- [x] `docs/WORKFLOWS.md` updated to match the Phase 2 CLI
- [x] Chain credence default behavior documented and tested
- [x] Wrapper fallbacks fixed
- [x] `/check` command has allowed-tools for automation

All 112 tests pass (17 skipped for embedding tests).
