# Reference parity map

Phase 1 ports behavior from the upstream review packages into Pythinker Review. This map is the
source-to-target contract for what is preserved now, what is deferred, and where tests should anchor
compatibility.

## `clawpatch-upstream`

| Upstream source module/prompt/rule/workflow | Behavior to preserve | Pythinker target path | Test coverage | Documented deviation |
| --- | --- | --- | --- | --- |
| `clawpatch-upstream/README.md`, `docs/index.md`, `docs/spec.md` | Review is evidence-first; state is durable; fix/PR flows are explicit follow-ups. | `reviewflow/workflow.py`, `reviewflow/state.py`, `packages/pythinker-review/src/pythinker_review/engine/orchestrator.py`, `store/` | Store round-trip, legacy state migration, stateful init/map/review/report/triage/fix e2e, list/show, fail-closed runner tests. | Diff review still persists `.pythinker-review/`; the stateful Reviewflow workflow uses `.pythinker-review-flow/` by default and non-destructively imports legacy state when needed. |
| `clawpatch-upstream/src/prompt.ts` review/fix/revalidate prompts | Bounded context, strict JSON, evidence/reasoning/test-analysis/minimum-fix-scope concepts, plus explicit unified-diff fix plans. | `reviewers/prompts/code_review.system.md`, `reviewers/prompts/debug_review.system.md`, `reviewers/prompts/deslopify_review.system.md`, `reviewers/schema.py`, `store/models.py`, `reviewflow/provider.py` | Reviewer prompt/caller tests, schema round-trip tests, malformed-output retry tests, fix unified-diff e2e. | Stateful feature review uses compact pure-Python prompts rather than a literal TypeScript prompt copy. |
| `clawpatch-upstream/src/review-validation.ts` | Reject stale/out-of-context evidence; never silently persist hallucinated findings. Stateful review records schema/evidence drops without failing valid sibling findings. | `reviewers/validation.py`, `engine/runner.py`, `reviewers/schema.py`, `reviewflow/provider.py`, `reviewflow/workflow.py` | Validation tests for escaping paths, out-of-chunk files, out-of-hunk line ranges, evidence snippets, prompt manifests, and non-fatal stateful validation drops. | Diff validation is chunk-scoped; stateful feature review is prompt-manifest-scoped with line-numbered excerpts. Full semantic feature-context validation beyond included excerpts remains deferred. |
| `clawpatch-upstream/src/app.ts` | Bounded worker pool, retry malformed model output once, run metadata, partial failure visibility, workflow commands. | `engine/runner.py`, `store/models.py`, `store/findings_store.py`, `reviewflow/workflow.py`, `cli/review.py` | Runner fail-closed/allow-partial tests; store atomicity tests; stateful workflow e2e. | Stateful feature review is intentionally conservative and pure Python; agent enrichment is not yet implemented. |
| `clawpatch-upstream/src/types.ts`, `src/mapper.ts`, `src/mappers/task-graph.ts` | Durable project/feature/run/finding/patch records and heuristic feature/task mapping. | `reviewflow/models.py`, `reviewflow/mapping.py`, `reviewflow/provider.py`, `reviewflow/state.py` | Pydantic schema import/type checks, mapper partition/script/state/report unit tests, package lint/typecheck. | Mapper coverage includes source partitioning, nearby-test association, Python console scripts, and broad file-pattern grouping; framework-specific mapper details are compacted rather than byte-identical. |
| `clawpatch-upstream/src/selection.ts`, `src/git.ts` | Git-scoped selection (`since`/dirty/range), changed-file focus, path-relative behavior. | `engine/diff_source.py`, `engine/chunker.py`, `reviewflow/workflow.py`, `reviewflow/utils.py` | Git fixture tests for base/staged/working-tree/range and glob filters; stateful changed-file selectors are covered through workflow tests. | Diff review remains hunk-scoped; stateful review is feature-scoped. |
| `clawpatch-upstream/src/reporting.ts` | Human and machine reports preserve evidence and recommended next action. | `output/pretty.py`, `output/json.py`, `output/sarif.py`, `reviewflow/reporting.py`, `cli/review.py` (`report`, `next`, `show --finding`) | Pretty/JSON/SARIF formatter tests; saved-finding next/show e2e tests; Reviewflow report unit/e2e tests. | Report clustering is compact, not a byte-identical TypeScript renderer. |
| `clawpatch-upstream/src/validation.ts`, `src/change-audit.ts`, `src/app.ts` fix/open-pr | Mutating fixes require explicit finding IDs, dirty-worktree safety, validation command tracking. | `reviewflow/provider.py`, `reviewflow/workflow.py`, `cli/review.py` (`fix`, `open-pr`) | `fix --dry-run`, out-of-scope diff rejection, unsafe PR argument rejection, and unified-diff apply e2e; package lint/typecheck. | `fix` applies model-returned unified diffs with `git apply` after scope validation; `open-pr` shells to git/gh with sanitized argv and remains explicit/dry-run capable. |

## `code-review-upstream`

| Upstream source module/prompt/rule/workflow | Behavior to preserve | Pythinker target path | Test coverage | Documented deviation |
| --- | --- | --- | --- | --- |
| `code-review-upstream/README.md`, `pyproject.toml` | Diff-scoped automated reviewer that can be used locally and in CI. | `packages/pythinker-review`, `cli/review.py`, `src/pythinker_code/cli/review.py` | CLI e2e tests for exit codes and JSON/SARIF output. | PR-provider write/comment integrations are deferred. |
| Code-review prompt/rules | Focus only on issues introduced by the diff; prefer no finding over vague speculation; cite concrete failure modes, changed lines, tests, minimum fix scope, optional extra review instructions, and max finding count. | `reviewers/prompts/code_review.system.md`, `reviewers/code_review.py`, `reviewers/schema.py`, `cli/review.py diff` | Reviewer strict-JSON, fenced-output cleanup, schema, prompt resource, extra-instruction, and max-finding tests. | Uses Pydantic JSON rather than the source project's YAML/native review serialization. |
| Structured diff workflow (`__new hunk__` / `__old hunk__`) | Preserve post-change line numbering and old/new comparison blocks. | `engine/structured_diff.py` | Added-file, deletion, binary-skip, line-number tests. | Renderer is lightweight stdlib Python, not a direct Python port of provider/UI code. |
| Token-aware diff/context compression | Keep review input bounded and split oversized files on hunk boundaries without cutting lines mid-stream. | `engine/context.py`, `engine/chunker.py`, `engine/token_budget.py` | Budget/window, line-preserving clipping, generated-file skip, and per-hunk chunk tests. | Exact token budgeting is character-budgeted in Phase 1. |
| Runtime flow/output parsing/no-findings behavior | Strict model output parsing; fenced JSON/prose-wrapped JSON is cleaned safely; malformed output is not a green no-finding result. | `reviewers/common.py`, `reviewers/*.py`, `engine/runner.py` | One-retry malformed JSON, fenced JSON cleanup, and fail-closed runner tests. | Standalone CLI uses fake/env configuration unless root `pythinker review` injects an active model. |
| `/describe`, `/improve`, `/ask`, `/ask_line`, `/generate_labels`, `/update_changelog`, `/add_docs`, `/help`, `/config` | Preserve PR assistant workflows as local read-only artifacts/tools over the same structured diff, including slash-command aliases, custom labels, best-practices/extra-instruction context, score filtering, line questions, changelog PR-link context, docs targeting, and static tool/config output. | `reviewers/artifacts.py`, `reviewers/pr_artifacts.py`, `reviewers/help_docs.py`, artifact prompt files, `cli/review.py` commands | Artifact schema/unit tests, CLI e2e tests, wrapper help tests. | Pythinker emits local JSON/pretty artifacts and does not publish provider comments or mutate PR metadata yet. |
| `/ask_line` | Answer a question about explicitly selected changed lines without provider thread publishing. | `reviewers/prompts/line_questions.system.md`, `cli/review.py ask-line` | Line-question artifact unit and CLI e2e tests. | Provider thread history fetching is deferred; optional history can be supplied locally. |
| `/help_docs` | Answer questions from bounded local repository docs. | `reviewers/help_docs.py`, `reviewers/prompts/help_docs.system.md`, `cli/review.py help-docs` | Help-docs artifact unit and CLI e2e tests. | Remote repo cloning/provider comment publishing is deferred. |
| `tools/ticket_pr_compliance_check.py`, `pr_compliance_checklist.yaml` | Preserve checklist/ticket compliance review without provider fetch side effects. | `reviewers/default_compliance.yaml`, `reviewers/compliance.py`, `reviewers/prompts/compliance.system.md`, `cli/review.py compliance` | Compliance artifact unit tests and CLI e2e test. | Ticket fetching from GitHub/Azure is deferred; users pass `--ticket-text` or `--ticket-file`. |
| `/help_docs`, `/similar_issue` | Preserve useful local forms without cloning remote docs or hosted providers: bounded local documentation Q&A, dependency-free lexical search over local issue documents, and optional in-memory ChromaDB vector search when installed separately; `--persist-index` explicitly enables local index writes. | `reviewers/help_docs.py`, `reviewers/similar_issues.py`, `reviewers/prompts/help_docs.system.md`, `cli/review.py` | Help-docs and similar-issues lexical/optional-Chroma unit/e2e tests. | Remote docs cloning, provider issue indexing, and Pinecone/LanceDB/Qdrant hosted backends are deferred. |
| Inline comments, provider write abstractions | Provider concepts inform later PR integration. | Future PR-provider phase. | Future provider adapter tests. | Local-agent port outputs artifacts only; hosted publishing remains intentionally out of scope. |

## `deepsec-upstream`

| Upstream source module/prompt/rule/workflow | Behavior to preserve | Pythinker target path | Test coverage | Documented deviation |
| --- | --- | --- | --- | --- |
| `deepsec-upstream/docs/reviewing-changes.md`, scanner/processor direct mode | Direct diff/file mode scans every selected file and fails loud on runtime errors. | `cli/secscan.py`, `engine/runner.py`, `engine/orchestrator.py` | Secscan e2e, empty/malformed output tests, exit-code tests. | Distributed processing is deferred; repo-wide persistence now lives under Pythinker Security Scan. |
| `packages/processor/src/agents/shared.ts` JSON parsing | Malformed/non-array model output is a batch error, not "no findings". | `reviewers/security_review.py`, `engine/runner.py` | Security reviewer retries once then records `malformed_output`; fail-closed runner tests. | Pythinker schema is `{"findings": [...]}` instead of the source scanner's array payload. |
| Security prompt core | Static-analysis mindset, trace inputs/imports/mitigations, report only validated exploitable issues. | `reviewers/prompts/security_review.system.md` | Prompt/caller tests and signal scanner tests. | Severity taxonomy maps to Pythinker `critical/high/medium/low/info`. |
| Scanner rule metadata/matchers | Deterministic signals are prompt anchors, not findings, and carry rule metadata/reasons/confidence/CWE/severity hints. | `signals/models.py`, `signals/scanner.py` | Secret, shell/RCE, SQL, NoSQL, deserialization, SSRF, path traversal, XSS, redirect, JWT, CORS, debug, prompt-injection, weak-crypto rule tests. | Curated in-process rules replace the source plugin marketplace for Phase 1. |
| Prompt assembly with tech highlights/slug notes/project context | Batch-scoped anchors avoid prompt bloat while preserving signal context. | `security_scan/knowledge.py`, `security_scan/tech.py`, `signals/advisor.py`, `reviewers/security_review.py`, `engine/orchestrator.py` | Advisor context, tech detection, and security reviewer prompt tests. | INFO.md/config prompt append remain deferred for diff review; shared built-in tech highlights and slug notes are implemented. |
| Revalidation/verdict workflow | Findings should be validated before being treated as final. | `reviewers/validation.py`, `engine/runner.py`; future read-only `revalidate.py` | Validation and fail-closed runner tests. | Separate saved-finding revalidation is deferred; initial model output is evidence-validated now. |
| Export/report/metrics | Machine-readable output and CI gating only on net findings. | `output/json.py`, `output/sarif.py`, `cli/_shared.py` | JSON/SARIF schema tests and threshold exit-code tests. | Markdown PR comments and metrics dashboards are deferred. |
