Update to LegalQuants Litigation

{
  "name": "docreview",
  "description": "Review an incoming litigation production against the matter's requests or issues, with deterministic inventory and coverage receipts, a plain-language setup approval, human privilege decisions, source-linked Requests/Documents HTML, and drift-bound lawyer feedback. Use when asked to organize or review a production, map documents to RFPs or pleadings, identify production gaps, or prepare a privilege queue.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 289
    },
    {
      "relative_path": "references/comms-schemas.md",
      "size_in_bytes": 16058
    },
    {
      "relative_path": "references/docreview-gate3-reconciliation.schema.json",
      "size_in_bytes": 4472
    },
    {
      "relative_path": "references/openai-codex-runtime.md",
      "size_in_bytes": 3545
    },
    {
      "relative_path": "references/privilege-rulings.schema.json",
      "size_in_bytes": 1236
    },
    {
      "relative_path": "references/review-feedback.schema.json",
      "size_in_bytes": 3225
    },
    {
      "relative_path": "references/review-setup-approval.schema.json",
      "size_in_bytes": 2177
    },
    {
      "relative_path": "references/shared/edge-resolver-prompt.md",
      "size_in_bytes": 782
    },
    {
      "relative_path": "references/shared/edge-resolver.schema.json",
      "size_in_bytes": 858
    },
    {
      "relative_path": "references/shared/execution-modes.md",
      "size_in_bytes": 7205
    },
    {
      "relative_path": "references/shared/finding-checker-prompt.md",
      "size_in_bytes": 1181
    },
    {
      "relative_path": "references/shared/finding-checker.schema.json",
      "size_in_bytes": 1021
    },
    {
      "relative_path": "references/shared/finding-worker-prompt.md",
      "size_in_bytes": 2214
    },
    {
      "relative_path": "references/shared/finding-worker.schema.json",
      "size_in_bytes": 4840
    },
    {
      "relative_path": "references/shared/framework-schema.md",
      "size_in_bytes": 11192
    },
    {
      "relative_path": "references/shared/framework.schema.json",
      "size_in_bytes": 5917
    },
    {
      "relative_path": "references/shared/inventory-design.md",
      "size_in_bytes": 7769
    },
    {
      "relative_path": "references/shared/metadata-reader-prompt.md",
      "size_in_bytes": 1777
    },
    {
      "relative_path": "references/shared/metadata-reader.schema.json",
      "size_in_bytes": 2596
    },
    {
      "relative_path": "references/shared/review-copies.schema.json",
      "size_in_bytes": 4090
    },
    {
      "relative_path": "references/shared/review-ui.md",
      "size_in_bytes": 7392
    },
    {
      "relative_path": "references/shared/schemas.md",
      "size_in_bytes": 13649
    },
    {
      "relative_path": "scripts/cluster_comms.py",
      "size_in_bytes": 7672
    },
    {
      "relative_path": "scripts/comms_gaps.py",
      "size_in_bytes": 9971
    },
    {
      "relative_path": "scripts/ingest_privilege_rulings.py",
      "size_in_bytes": 5290
    },
    {
      "relative_path": "scripts/ingest_review_feedback.py",
      "size_in_bytes": 17969
    },
    {
      "relative_path": "scripts/ingest_review_setup_approval.py",
      "size_in_bytes": 7283
    },
    {
      "relative_path": "scripts/parse_messages.py",
      "size_in_bytes": 6704
    },
    {
      "relative_path": "scripts/reconcile_docreview_gate3.py",
      "size_in_bytes": 12885
    },
    {
      "relative_path": "scripts/render_crosswalk.py",
      "size_in_bytes": 94593
    },
    {
      "relative_path": "scripts/render_dmap.py",
      "size_in_bytes": 45436
    },
    {
      "relative_path": "scripts/render_privilege_queue.py",
      "size_in_bytes": 23458
    },
    {
      "relative_path": "scripts/shared/admit_finding_result.py",
      "size_in_bytes": 11618
    },
    {
      "relative_path": "scripts/shared/block_candidates.py",
      "size_in_bytes": 6123
    },
    {
      "relative_path": "scripts/shared/build_checker_plan.py",
      "size_in_bytes": 6620
    },
    {
      "relative_path": "scripts/shared/build_families.py",
      "size_in_bytes": 17253
    },
    {
      "relative_path": "scripts/shared/build_manifest.py",
      "size_in_bytes": 14974
    },
    {
      "relative_path": "scripts/shared/build_review_plan.py",
      "size_in_bytes": 10183
    },
    {
      "relative_path": "scripts/shared/document_text.py",
      "size_in_bytes": 12579
    },
    {
      "relative_path": "scripts/shared/export_register.py",
      "size_in_bytes": 9522
    },
    {
      "relative_path": "scripts/shared/extract_metadata_prep.py",
      "size_in_bytes": 22543
    },
    {
      "relative_path": "scripts/shared/finding_validation.py",
      "size_in_bytes": 11839
    },
    {
      "relative_path": "scripts/shared/merge_checker_results.py",
      "size_in_bytes": 11453
    },
    {
      "relative_path": "scripts/shared/merge_edge_results.py",
      "size_in_bytes": 6638
    },
    {
      "relative_path": "scripts/shared/merge_finding_results.py",
      "size_in_bytes": 21121
    },
    {
      "relative_path": "scripts/shared/merge_metadata_reads.py",
      "size_in_bytes": 28694
    },
    {
      "relative_path": "scripts/shared/parse_instruments.py",
      "size_in_bytes": 15685
    },
    {
      "relative_path": "scripts/shared/prepare_review_jobs.py",
      "size_in_bytes": 4843
    },
    {
      "relative_path": "scripts/shared/reconcile_counts.py",
      "size_in_bytes": 18863
    },
    {
      "relative_path": "scripts/shared/reconcile_index.py",
      "size_in_bytes": 11453
    },
    {
      "relative_path": "scripts/shared/render_gate1.py",
      "size_in_bytes": 20125
    },
    {
      "relative_path": "scripts/shared/render_readback.py",
      "size_in_bytes": 6071
    },
    {
      "relative_path": "scripts/shared/render_report.py",
      "size_in_bytes": 24035
    },
    {
      "relative_path": "scripts/shared/render_sample.py",
      "size_in_bytes": 23901
    },
    {
      "relative_path": "scripts/shared/review_copies.py",
      "size_in_bytes": 77410
    },
    {
      "relative_path": "scripts/shared/review_ui.py",
      "size_in_bytes": 6747
    },
    {
      "relative_path": "scripts/shared/run_codex_finding_worker.py",
      "size_in_bytes": 15135
    },
    {
      "relative_path": "scripts/shared/run_review_jobs.py",
      "size_in_bytes": 25042
    },
    {
      "relative_path": "scripts/shared/validate_framework.py",
      "size_in_bytes": 21626
    },
    {
      "relative_path": "scripts/shared/verify_quotes.py",
      "size_in_bytes": 8174
    }
  ],
  "skill_md_contents": "---\nname: docreview\ndescription: Review an incoming litigation production against the matter's requests or issues, with deterministic inventory and coverage receipts, a plain-language setup approval, human privilege decisions, source-linked Requests/Documents HTML, and drift-bound lawyer feedback. Use when asked to organize or review a production, map documents to RFPs or pleadings, identify production gaps, or prepare a privilege queue.\n---\n\n# Document Review\n\n## Outcome and boundaries\n\nTurn a local production into a coverage-receipted review package: inventory,\ncommunication map, gaps, approved review questions, immutable machine\nproposals, lawyer-only privilege decisions, a Requests/Documents review page,\nlawyer-feedback overlays, and final reconciliation.\n\nThe lawyer decides responsiveness, relevance, materiality, and privilege. This\nskill proposes and verifies; it does not produce, serve, file, or transmit\ndocuments. A privilege signal always creates a hold until the lawyer rules.\n\nKeep the machine proposal ledger and its evidence receipts immutable. Setup\napprovals, privilege rulings, image confirmations, and responsiveness rulings\nare additive artifacts or overlays bound to the exact inputs they govern.\n\n## Read the applicable contracts\n\n- Before inventory or scheduling, read\n  [execution-modes.md](references/shared/execution-modes.md),\n  [inventory-design.md](references/shared/inventory-design.md), and the\n  relevant artifact definitions in [schemas.md](references/shared/schemas.md).\n- Before message clustering, privilege review, setup approval, feedback\n  ingestion, or final reconciliation, read\n  [comms-schemas.md](references/comms-schemas.md).\n- Before compiling review questions, read\n  [framework-schema.md](references/shared/framework-schema.md). For an\n  enumerated request set, use the adjacent machine schema and preserve every\n  served element.\n- Before dispatching judgment work, read the matching metadata-reader,\n  finding-worker, or finding-checker prompt and schema in\n  `references/shared/`. When a permitted local headless runtime will execute\n  the compact finding jobs, also read its provider reference before choosing\n  the worker command.\n- Before producing lawyer-facing HTML, read\n  [review-ui.md](references/shared/review-ui.md) and\n  [review-copies.schema.json](references/shared/review-copies.schema.json).\n  Before ingesting a browser export, read its adjacent receipt schema.\n\nOnly confirmed `[docreview]` lines in `lqplaybook.md` may shape the work. Do\nnot read `lqprofile.md` during a review run.\n\n## Runtime and assurances\n\nPrefer the bundled Python path. Every bundled Python script uses the standard\nlibrary only. Try `python3`, then `python`, then `py -3`; confirm the selected\ninterpreter can run a bundled script's `--help`. Do not install Python packages\nor change the host.\n\nPoppler and LibreOffice are optional, open-source rendering rungs when already\navailable. They are executables, not Python dependencies. The core text,\nemail, OOXML, hashing, receipt, and HTML paths remain offline and standard\nlibrary only.\n\nIf local scripts cannot run, follow the portable fallback in\n`execution-modes.md`, using isolated workers when available and the same jobs\nsequentially otherwise. Preserve every privilege hold and lawyer gate. State\nwhich deterministic checks were unavailable; without stable file identity and\ncomplete count reconciliation, do not call the result coverage-certified.\n\nUse one run directory for intermediate state and one source root for the\nproduction. Durable artifacts contain relative paths, stable IDs, sorted JSON,\nno run-added timestamps, no host names, and no external URLs.\n\nFor finding jobs, prefer `scripts/shared/prepare_review_jobs.py` followed by\n`scripts/shared/run_review_jobs.py`. The runner defaults to five concurrent\njobs and accepts `--workers 1..12`. Before fan-out, surface its run-started\ndisclosure: selected concurrency, source of that setting, job count, estimated\ninvocations, and the resource/throttling tradeoff. Keep one model and effort\nfor the whole run and record them in the journal. Do not read or modify a\nhost's global configuration to choose concurrency.\n\nThe runner preserves immutable attempts, admits compact responses through\n`admit_finding_result.py`, writes canonical checkpoints and deterministic\nreceipts, and journals every transition. Report progress from `progress.json`\nand failures from `parked.json`. Use `--detach` when the execution must survive\nthe parent conversation. A parked job remains stopped until an explicit\n`unpark --by ... --reason ...` receipt.\n\n## Workflow\n\n### 1. Inventory the production and build review copies\n\nRun `scripts/shared/build_manifest.py` over the production root. When the\nproduction includes an index or load file, run\n`scripts/shared/reconcile_index.py`; retain every manifest, duplicate,\nunreadable, and index gap.\n\nAfter the manifest is final, build the mandatory review-copy layer:\n\n```text\nscripts/shared/review_copies.py build \\\n  --manifest <run>/manifest.json \\\n  --source-root <production> \\\n  --sidecar <run>/review-copies.json \\\n  --bundle-root review-copies \\\n  --mode auto\n```\n\nKeep `review-copies.json`, its `review-copies/` bundle, and every HTML file\nthat consumes it in the same directory. The sidecar binds the canonical\nmanifest digest, every source hash and byte count, separately reviewable email\nattachments, every derivative hash, and the exact bundle contents. It carries\nno legal conclusion.\n\nThe built-in path renders escaped text and EML, common images, browser-native\nPDF, and safe visible text from readable DOCX, XLSX, and PPTX packages.\n`--mode auto` adds Poppler pages and LibreOffice-to-Poppler Office pages when\nthose tools are already present. Legacy, corrupt, unsupported, or incomplete\nformats remain **Needs rendering**.\n\nExit 0 means all documents and separately reviewable attachments are ready.\nExit 1 means the sidecar is valid but at least one item still needs rendering;\npark every dependent review result and do not approve that tier. Exit 2 means\nintegrity or containment failed; stop and repair the source, manifest, or\nbundle before continuing.\n\n### 2. Map the production and plan reads\n\nRun `scripts/parse_messages.py`, `scripts/cluster_comms.py`, and\n`scripts/comms_gaps.py`. Thread membership comes from message headers and\nreference chains; channels come from repeated participant sets. Flattened\nPDFs and images remain singleton units. Never infer a custodian, date,\nparticipant, or thread from a filename.\n\nRun `scripts/shared/extract_metadata_prep.py`. For message-heavy request\nreview, pass `messages.json` through `--include-ids` so non-message files are\nexplicitly planned. Build both ordinary and\n`--defer-non-unit-metadata` plans when canonical metadata is unnecessary, and\nlet the lawyer choose that policy during setup. Deferred files remain fully\nin scope for the finding pass. Only `scripts/shared/merge_metadata_reads.py`\nwrites canonical metadata.\n\n### 3. Compile and read back the review questions\n\nThe lawyer supplies the request sets, pleadings, chronology, or issue list.\nFor served or otherwise enumerated instruments, run\n`scripts/shared/parse_instruments.py` first. Show the complete census and use\n`--scaffold` for a one-item-per-element requests framework. Preserve served\nnumbers, series, and text; leave sets outside this run visibly staged.\n\nFor prose framing inputs, compile conservative issue questions without\ninventing legal positions. Include the four privilege signals defined in\n`comms-schemas.md`. Run `scripts/shared/validate_framework.py` with the\ninstrument census and manifest when applicable, then\n`scripts/shared/render_readback.py`. The validated framework is the only\ninstruction channel to makers and checkers.\n\n### 4. Obtain a plain-language setup approval\n\nChoose up to five representative thread or singleton units and run\n`scripts/shared/build_review_plan.py --tier sample`. Render\n`scripts/render_dmap.py` with the manifest, messages, clusters, gaps, read\nplan, review plan, `--framework`, its derived framework readback, execution\nmode, assurance note,\n`--document-root`, and the sibling `--review-copies` sidecar. The setup page\nrevalidates the complete sidecar and disables sample approval while any source\nor separately reviewable attachment still needs rendering.\n\nThe visible page asks the lawyer to decide:\n\n1. Are these the right review questions?\n2. Does the collection coverage look right?\n3. Is this a useful test sample?\n4. If proposed, may standalone metadata reads be deferred to the issue pass?\n\nThe page must say that approval authorizes only the displayed test sample. It\ndoes not authorize a full run, change a privilege hold, or start work merely\nbecause the button was clicked. Plans, hashes, worker mechanics, and IDs stay\nin collapsed technical receipts.\n\nIngest `review-setup-approval.json` with\n`scripts/ingest_review_setup_approval.py`. It must refuse corpus, framework,\ncluster, read-plan, review-plan, unit, issue, or metadata-policy drift before\nwriting `review-plan.approved.json` and `clusters.confirmed.json`. Start the\nsample only after successful ingest or an explicit conversation approval\nrecorded in the same receipt shape. A bare “continue” is not approval.\n\n### 5. Run and merge the test sample\n\nMaterialize the approved plan with `prepare_review_jobs.py`. Give each\nunit/lens assignment isolated contexts containing only its documents, a\nbounded request batch, exact plan and job IDs, and the compact finding-worker\ncontract. Follow the substantive mapping quality gate in\n`references/shared/execution-modes.md`: select a higher-capability reasoning\nroute, use medium effort or above, cap each model context at 12 requests, and\nprove recall on source-verified sample positives before scale. Use\n`run_review_jobs.py run` for an authorized scripted fan-out; otherwise give\nthe same bounded assignments to native workers or process them sequentially.\nThe worker echoes only the plan and job IDs. The admitter binds\ndocument ordinals, constructs every document and finding ID, expands compact\nnegative rows, verifies receipts, and writes the canonical checkpoint. Retry\na rejected judgment at most twice, then park it with a reason; transport\nfailures have a separate bounded budget.\n\nRun `scripts/shared/merge_finding_results.py` with the approved plan,\nframework, manifest, production root, confirmed clusters, and results\ndirectory. It revalidates admitted checkpoints before writing the proposal\nledger or privilege queue. Missing jobs, invalid quotes, outside-tier units,\nand privilege-held units remain parked.\n\n### 6. Obtain lawyer privilege rulings\n\nBefore showing dependent findings, render every pending candidate with\n`scripts/render_privilege_queue.py`. A candidate's source must be present and\nits `review-copies.json` entry must be ready before asking the lawyer to rule;\nthe original-file link is provenance, not a substitute for the verified\nreview copy.\n\nThe lawyer chooses **Privileged**, **Not privileged**, or **Need more review**\nfor every candidate and exports `privilege-rulings.json`. Ingest it with\n`scripts/ingest_privilege_rulings.py`. Queue or manifest drift must fail before\noutput. The source queue remains unchanged; the ruled copy preserves the\ncandidate evidence and adds only the lawyer ruling and note.\n\nRerun the finding merger with the ruled queue. Only `not-privileged` releases\na unit. Pending, `privileged`, and `needs-review` records remain held across\nevery lens.\n\n### 7. Verify findings independently\n\nBuild a checker plan with `scripts/shared/build_checker_plan.py` after\nprivilege rulings. Every present high-band finding goes to a fresh checker\nwithout the maker's reasoning. Merge checker outputs with\n`scripts/shared/merge_checker_results.py`. Missing, stale, drifted, or\nnon-confirming results become unresolved; they never disappear.\n\nRender the checked sample with `scripts/shared/render_sample.py` for the\ninternal calibration receipt. If lawyer feedback changes a framework field,\ncompile a new framework version and obtain a new plan approval before running\nagain. Approval freezes the calibrated version.\n\n### 8. Review findings in Requests and Documents\n\nBefore every lawyer-facing findings render, verify the sidecar against the\ncurrent source bytes and manifest. Then run `scripts/render_crosswalk.py` with\n`--document-root`, `--review-copies`, and the framework, checked findings,\nmanifest, and ruled privilege queue. The sidecar and HTML must be siblings.\nAny sidecar integrity error stops rendering.\n\nThe default **Requests** tab answers which documents respond to each request.\nThe **Documents** tab reverses the same ledger and renders each source once.\nResponsive items appear first; reviewed negatives are collapsed by default.\nAn unresolved legal call is **Needs a decision**, not “unreadable.” A file\nwith unresolved calls appears once in **Needs attention**, and a rendering\nfailure appears as **Needs rendering**. Outside-tier documents are never\ncalled nonresponsive.\n\nThe page works from `file://`, loads no remote resource, and exports sorted,\ntimestamp-free `review-feedback.json`. The lawyer may rule a finding\n**Responsive**, **Not responsive**, **Needs review**, or **Privileged** and\nmay separately confirm an image document's complete finding bundle.\n\nIngest feedback with `scripts/ingest_review_feedback.py`. It must refuse stale\nledger, framework, plan, frame, corpus, machine-status, finding, or image-bundle\nbindings before writing. It never overwrites the proposal ledger or alters a\nmachine status, quote, evidence receipt, checker receipt, or privilege queue.\nPer-finding `lawyer_ruling` and top-level `image_confirmations` are additive\noverlays only.\n\nRe-render the ruled copy using the existing artifacts. Export, ingest, and\nrerender are deterministic file operations and require no new model call.\n\n### 9. Scale only after calibration\n\nBuild a new targeted or full review plan from the frozen framework and\nconfirmed clusters. Show the exact scope, higher-capability model class,\nreasoning effort, request-batch limit, projected model-call count, and cost\nbasis and obtain explicit approval of that plan before dispatch. Prepare the\nsame bounded assignments, surface the run-started disclosure, and run the same\nadmission, privilege, checker, review-copy, lawyer-feedback, and rerender\nsequence. Resume only from attempts and checkpoints whose raw hashes, receipts,\nand plan bindings still validate. Never resume a parked job without a receipted\nunpark.\n\n### 10. Reconcile and deliver\n\nRun `scripts/reconcile_docreview_gate3.py` with the exact manifest, ruled\nfindings overlay, framework, confirmed clusters, privilege queue, and approved\nreview plan. It must prove the complete issue-by-unit count equation and exact\nlawyer confirmation of every image-review bundle. Fix the run, never the\nnumbers.\n\nFinally run:\n\n```text\nscripts/shared/review_copies.py verify \\\n  --manifest <run>/manifest.json \\\n  --source-root <production> \\\n  --sidecar <run>/review-copies.json\n```\n\nDelivery requires exit 0. Exit 1 leaves a visible rendering blocker; exit 2\nmeans integrity failure. Neither state is lawyer-reviewed, client-ready, or\ncoverage-certified.\n\n## Completion criteria\n\n- Every source is accounted for as reviewed, parked with a reason, or outside\n  the explicitly approved tier; the count reconciliation exits 0.\n- The setup receipt was ingested before the sample, and the lawyer explicitly\n  approved the exact full-plan ID and scope before full review started.\n- The sample recovered every source-verified positive under the same model\n  class, effort, and request-batch limit used for scale; schema validity and\n  runtime speed alone are not calibration.\n- Every privilege candidate has an explicit lawyer ruling, and no held unit\n  contributes a deliverable finding.\n- Every present high-band finding has an independent checker confirmation;\n  every quote and source membership check passed or became unresolved.\n- `review-copies.json` verifies at exit 0 against the final manifest, source\n  bytes, derivatives, attachments, and bundle contents.\n- Setup, privilege, sample, and Requests/Documents HTML were regenerated and\n  exercised from `file://` in light and dark mode, including tabs, filters,\n  keyboard/focus hooks, downloads, and blocked states.\n- A second render from identical inputs is byte-identical. Rerendering used no\n  model call.\n- Temporary working state is removed at completion; deliverables remain in the\n  matter folder and nothing was transmitted.\n"
}