@quickchatai/pi-quickreview 0.0.0-stage → 1.1.0

package/assets/schemas/scan-result.v1.json

@@ -0,0 +1,421 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "scan-result.v1.json",
+  "title": "qcr scan --json, version 1",
+  "description": "One JSON object per `qcr scan <verb> --json`. schema_version leads every payload; ok says whether the call succeeded. Fields beyond those named may appear without a version change; a caller ignores what it does not know and refuses a schema_version it does not know. A refusal is {ok:false, errors:[\u2026]}. Verbs not named here (stage2, units, doctor, dismiss, match, suggestions) carry their own fields beside ok and schema_version.",
+  "type": "object",
+  "required": ["schema_version", "ok"],
+  "properties": {
+    "schema_version": {
+      "const": 1,
+      "description": "This schema's version."
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "errors": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "preview": {
+      "$ref": "#/$defs/preview"
+    },
+    "start": {
+      "type": ["array", "null"],
+      "items": {
+        "type": "string"
+      },
+      "description": "preview: the arguments that start this exact scan; null when a blocker stands in the way."
+    },
+    "run": {
+      "description": "status, start --foreground: the run, or null when none has run. A detached start: a summary {id, mode, sha, cases (a count), cap_usd}. stop: the stopped run's id.",
+      "anyOf": [
+        { "type": "null" },
+        { "type": "string" },
+        { "$ref": "#/$defs/runStatus" },
+        { "$ref": "#/$defs/runStarted" }
+      ]
+    },
+    "problems": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "active": {
+      "type": "boolean"
+    },
+    "history": {
+      "type": "array"
+    },
+    "ledger": {
+      "type": "object"
+    },
+    "timed_out": {
+      "type": "boolean",
+      "description": "status --wait gave up after --timeout; the scan is still going."
+    },
+    "total": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "findings: how many match, before --limit."
+    },
+    "validity": {
+      "type": "object",
+      "description": "findings: the matching findings counted by validity."
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/finding"
+      }
+    },
+    "question": {
+      "type": ["object", "null"]
+    },
+    "log": {
+      "type": "string"
+    },
+    "container": {
+      "type": "string"
+    },
+    "image": {
+      "type": "string"
+    },
+    "stamp": {
+      "type": "string"
+    }
+  },
+  "$defs": {
+    "runStatus": {
+      "type": "object",
+      "required": [
+        "id",
+        "mode",
+        "sha",
+        "state",
+        "display",
+        "started_at",
+        "cases_total",
+        "cases_done",
+        "cases_failed",
+        "findings",
+        "doubted",
+        "cases"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "mode": {
+          "type": "string"
+        },
+        "sha": {
+          "type": "string"
+        },
+        "state": {
+          "type": "string"
+        },
+        "display": {
+          "type": "string"
+        },
+        "depth": {
+          "type": "string"
+        },
+        "started_at": {
+          "type": "string"
+        },
+        "finished_at": {
+          "type": ["string", "null"]
+        },
+        "cap_usd": {
+          "type": ["number", "null"]
+        },
+        "estimate_usd": {
+          "type": ["number", "null"]
+        },
+        "spent_usd": {
+          "type": ["number", "null"]
+        },
+        "unpriced_cases": {
+          "type": "integer"
+        },
+        "cases_total": {
+          "type": "integer"
+        },
+        "cases_done": {
+          "type": "integer"
+        },
+        "cases_failed": {
+          "type": "integer"
+        },
+        "findings": {
+          "type": "integer"
+        },
+        "doubted": {
+          "type": "integer"
+        },
+        "matching": {
+          "type": ["object", "null"]
+        },
+        "tickets_closed": {
+          "type": "integer"
+        },
+        "problems": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "cases": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "unit", "status", "findings", "doubted", "cost_usd", "error"],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "unit": {
+                "type": "string"
+              },
+              "status": {
+                "type": "string"
+              },
+              "findings": {
+                "type": "integer"
+              },
+              "doubted": {
+                "type": "integer"
+              },
+              "cost_usd": {
+                "type": ["number", "null"]
+              },
+              "error": {
+                "type": ["string", "null"]
+              },
+              "lens": {
+                "type": "string"
+              },
+              "tier": {
+                "type": ["string", "null"]
+              }
+            }
+          }
+        }
+      }
+    },
+    "runStarted": {
+      "type": "object",
+      "required": ["id", "mode", "sha", "cases", "cap_usd"],
+      "properties": {
+        "id": { "type": "string" },
+        "mode": { "type": "string" },
+        "sha": { "type": "string" },
+        "cases": { "type": "integer" },
+        "cap_usd": { "type": "number" }
+      }
+    },
+    "seen": {
+      "type": "object",
+      "required": ["run", "sha"],
+      "properties": {
+        "run": {
+          "type": "string"
+        },
+        "sha": {
+          "type": "string"
+        }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "required": [
+        "fingerprint",
+        "file",
+        "range",
+        "lens",
+        "lenses",
+        "unit",
+        "kind",
+        "severity",
+        "validity",
+        "state",
+        "claim",
+        "doubted",
+        "doubt",
+        "looks_like_dismissed",
+        "dismissal_reason",
+        "ticket",
+        "first_seen",
+        "last_seen"
+      ],
+      "properties": {
+        "fingerprint": {
+          "type": "string"
+        },
+        "file": {
+          "type": "string"
+        },
+        "range": {
+          "type": "object",
+          "required": ["start", "end"],
+          "properties": {
+            "start": {
+              "type": "integer"
+            },
+            "end": {
+              "type": "integer"
+            }
+          }
+        },
+        "lens": {
+          "type": "string"
+        },
+        "lenses": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "unit": {
+          "type": "string"
+        },
+        "kind": {
+          "type": "string"
+        },
+        "severity": {
+          "type": "string"
+        },
+        "validity": {
+          "type": "string"
+        },
+        "state": {
+          "type": "string"
+        },
+        "claim": {
+          "type": "string"
+        },
+        "doubted": {
+          "type": "boolean"
+        },
+        "doubt": {
+          "type": ["object", "null"],
+          "properties": {
+            "word": {
+              "type": "string"
+            },
+            "reason": {
+              "type": "string"
+            },
+            "class": {
+              "type": ["string", "null"]
+            }
+          }
+        },
+        "looks_like_dismissed": {
+          "type": ["object", "null"],
+          "properties": {
+            "fingerprint": {
+              "type": "string"
+            },
+            "reason": {
+              "type": "string"
+            }
+          }
+        },
+        "dismissal_reason": {
+          "type": ["string", "null"]
+        },
+        "ticket": {
+          "type": ["string", "null"]
+        },
+        "first_seen": {
+          "$ref": "#/$defs/seen"
+        },
+        "last_seen": {
+          "$ref": "#/$defs/seen"
+        }
+      }
+    },
+    "preview": {
+      "type": "object",
+      "required": [
+        "key",
+        "mode",
+        "sha",
+        "cases",
+        "files",
+        "lines",
+        "estimate_usd",
+        "cap_usd",
+        "depth",
+        "blockers"
+      ],
+      "properties": {
+        "key": {
+          "type": "string",
+          "description": "Quote it with start --key to confirm exactly this scan."
+        },
+        "mode": {
+          "type": "string"
+        },
+        "sha": {
+          "type": "string"
+        },
+        "cases": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "files", "lines", "estimate_usd"],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "files": {
+                "type": "integer"
+              },
+              "lines": {
+                "type": "integer"
+              },
+              "estimate_usd": {
+                "type": ["number", "null"]
+              }
+            }
+          }
+        },
+        "files": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "lines": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "estimate_usd": {
+          "type": ["number", "null"]
+        },
+        "cap_usd": {
+          "type": ["number", "null"]
+        },
+        "depth": {
+          "type": "string"
+        },
+        "blockers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "settings": {
+          "type": "object"
+        },
+        "delta": {
+          "type": ["object", "null"]
+        }
+      }
+    }
+  }
+}

package/assets/schemas/version.v1.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "version.v1.json",
+  "title": "qcr version --json, version 1",
+  "description": "What a plugin checks before it talks to this install: the image's version, the schema versions of the review and scan payloads, and the pi pin.",
+  "type": "object",
+  "required": ["schema_version", "image", "schemas", "pi"],
+  "properties": {
+    "schema_version": {
+      "const": 1,
+      "description": "This schema's version."
+    },
+    "image": {
+      "type": "object",
+      "required": ["version", "build_sha"],
+      "properties": {
+        "version": {
+          "type": "string",
+          "description": "package.json's version."
+        },
+        "build_sha": {
+          "type": ["string", "null"],
+          "description": "The stamp baked into a rebuilt image; null on a bare checkout."
+        }
+      }
+    },
+    "schemas": {
+      "type": "object",
+      "required": ["review", "scan"],
+      "properties": {
+        "review": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "schema_version of review-result payloads."
+        },
+        "scan": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "schema_version of scan-result payloads."
+        }
+      }
+    },
+    "pi": {
+      "type": ["object", "null"],
+      "required": ["package", "version"],
+      "properties": {
+        "package": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        }
+      },
+      "description": "The pinned pi; null when no pin is found."
+    }
+  }
+}

package/assets/seed-manifest.json

@@ -0,0 +1,19 @@
+{
+  "_comment": "AGENTS.md invariant 3: these files are SEEDED and canonical - byte-identical to the in-repo canonical copies under seeds/ (which carry the seeding lineage). Never edit them; per-pass model overrides go through the repo profile's [lenses.<pass>] effort / min_tier. Regenerate this manifest ONLY alongside a ratified reseed that refreshes seeds/ in the same commit.",
+  "source": "seeds/ (in-repo canonical copies; lineage: the seeding)",
+  "algorithm": "sha256",
+  "files": {
+    "agents/pass-baseline.md": "192ceadfed2096ce5f003b862c9942d7382110586d46adb04909784e180b7376",
+    "agents/pass-contracts.md": "f1cc07a83d5e694469c6a118ddaa3597e69fa783fc146073d200562f8bfe70a9",
+    "agents/pass-data-safety.md": "a6975823ca134fc7563fe0d68bade4da9d235bcaefa2ddd4168e87f43957e59e",
+    "agents/pass-delivery.md": "7ed59d92860a7e8d502a144b3e2784905695ff98675325ab540c7761029bab9c",
+    "agents/pass-prod-risk.md": "268daaa232d4a52fad1256c0a4407c6c19da39fd4e8797c603b24daed5033d9d",
+    "agents/pass-security.md": "b37dfb0f72297f868be4e741687241592a47ef8c197641df797810414ba6458b",
+    "agents/pass-statelessness.md": "089aca3cb3c818da6f3231eb3938d1ec7315b5a5158fa2ce6843b527b5e87451",
+    "agents/pass-ui.md": "7fe99149cc1f174f3b035911f86d93dad96ba493401495443a205e889a09eea6",
+    "agents/pass-validate.md": "cf28b7b2dd26b63265a4330c538ce3993dd03bda778810c2c199937195e4bb67",
+    "prompts/conversation-system.md": "28ee082e24caaf58c611b210663a81557199471724ba1a8ec0458480b91abfa1",
+    "prompts/eod-sweep.md": "9df21d94327f2f4475e95cd4337174d81efbe5dd8f5d6589d3c7788ff1d375f1",
+    "prompts/pass-common.md": "02e8a25d958f92745513474519b571e03205ddb1a50493146483447108689450"
+  }
+}

package/assets/seeds/agents/pass-baseline.md

@@ -0,0 +1,61 @@
+---
+name: pass-baseline
+description: Always-on review pass — claimed invariants, correctness, tests, conventions, sibling PRs.
+tools: read, bash, grep, glob
+---
+
+{{include:prompts/pass-common.md}}
+
+# Lens: baseline (every PR)
+
+**Claimed invariant — review the claim, not just the diff.** The PR's
+title/body claim defines the review scope. If it claims a property
+("retry-safe", "no message is dropped", "silences X", "fixes Y"), verify the
+property holds across the *whole mechanism*, not just the changed lines:
+enumerate the cases the claim covers and check each against the code. Two hard
+rules: (a) **"pre-existing" is not a valid demotion** for a failure inside the
+claimed failure class — a known drop path in a "nothing is dropped" PR is
+in-scope by definition and is P1; (b) verify **efficacy**, not just safety —
+confirm the mechanism can actually produce the claimed effect (trace the
+arithmetic, the log levels, the control flow to the promised outcome). For
+heuristic/fallback fixes, ask the root-cause question: *what upstream bug
+creates this state, and where is it fixed?* — P3 question if the PR only
+papers over it.
+
+**Correctness** — Does the code do what it claims? Trace the logic. Edge cases
+(empty/null/missing keys, concurrency)? Asynchronous code correct (no missing
+awaits, no blocking calls on async paths)? Database access free of N+1
+queries (a query per row where one query or a join would do)? When the diff
+assembles text from fragments (LLM prompts, templates, user-facing messages),
+**assemble a sample of the final string by reading** (join the literals
+and format calls by hand) and inspect the seams —
+whitespace, newlines, separators. No literal placeholder token may be
+reachable in an outbound message without a guaranteed fallback (remember a
+truthiness check is false on an empty string).
+
+**Tests** — New features must have tests, in the shape the repo's existing
+tests already use. Missing tests for a real feature is **P1**. Verify the
+headline regression test actually **exercises the guarded branch**, by
+reading: what value does the assertion compare, and is that value still
+produced when the bug is present? (A helper that returns the key itself for a
+missing translation makes `contains(key)` hold for any broken key.) Say which
+value and why in `evidence`; whether the suite passes comes from CI. If the PR
+edits a prompt, fallback template, or other string that a test pins verbatim
+(an expected-value constant, a golden file, a snapshot), the pinned copy must
+be updated in the same PR.
+
+**Conventions** (from the repo's own agent-directive files — AGENTS.md,
+CLAUDE.md and kin — and its contributing guide) — flag violations as **nit**
+unless they cause a bug. Judge against the conventions the repo writes down,
+never against another codebase's habits.
+
+**Sibling / template PRs** — If the PR is part of a series ("Phase 2/3",
+"Follow-up to …", or the same template applied to a different integration),
+read the sibling PR's diff and compare. Any divergence in the security or
+correctness contract is suspicious: either the sibling has a bug this PR fixes
+(call it out so the sibling gets patched too), or this PR is regressing a
+check the sibling intentionally got right.
+
+**Re-review duty** — when the task string lists prior findings to verify,
+check each **mechanically at the current head** first and report its true
+state (`fixed@sha` with evidence, or still-open) before hunting new findings.

package/assets/seeds/agents/pass-contracts.md

@@ -0,0 +1,30 @@
+---
+name: pass-contracts
+description: External-contracts review pass — provider payloads verified field-by-field, acceptance semantics, caveat owners.
+tools: read, bash, grep, glob
+---
+
+{{include:prompts/pass-common.md}}
+
+# Lens: external contracts
+
+Apply to: new/changed payloads to external providers (third-party APIs,
+payment, messaging, analytics and model services).
+
+For any new or changed payload to an external provider: (a) verify the
+contract **field by field against the provider's docs** — endpoint, id
+formats, timestamp format, required fields including consent/privacy fields;
+(b) any "unverified / provisional / TODO-confirm before go-live" marker
+shipping into a live credentialed path is P1 — require a live probe or hard
+dormancy with a tracked activation step; (c) any **intra-PR contradiction**
+about the contract (code vs docs vs tests vs PR body disagreeing on an id
+format or field meaning) is P1 on its own; (d) **HTTP 2xx is transport, not
+acceptance** — fire-and-forget sends must parse the response body's acceptance
+semantics (`accepted_events`, `errors[]`) and log/alert on shortfall; (e) a
+new ad/analytics sink is not "verified" until the *platform side* shows a
+credited event — require that evidence or an explicit post-deploy verification
+step with an owner. **Caveats need owners**: every acknowledged
+gap/limitation/follow-up in the PR body must map to a tracked artifact
+(ticket, monitor, TODO with an owner) — raise a P2 question listing any that
+don't; a risk that lives only in merged-PR prose is a production defect on a
+timer.

package/assets/seeds/agents/pass-data-safety.md

@@ -0,0 +1,54 @@
+---
+name: pass-data-safety
+description: Data-safety review pass — migrations DDL, blast radius, backfills; carries the migration gate.
+tools: read, bash, grep, glob
+---
+
+{{include:prompts/pass-common.md}}
+
+# Lens: data safety (assume the repo's hot tables hold millions of rows)
+
+Apply to: migrations, backfills, bulk writes, scheduled jobs that fan out per
+row.
+
+- **Migrations** — judge from the migration file and the model diff: the
+  operation types, `NOT NULL` adds, `DROP COLUMN`, added defaults, data-step
+  and raw-SQL bodies, index adds on large tables. Does the operation change
+  metadata only, scan the table, or rebuild it while holding a write lock? A
+  metadata-only change is deploy-safe; a scan still costs; a rebuild
+  write-locks for its whole run. Where the real DDL decides it and cannot be
+  read off the operation, ask the author for the rendered DDL in a
+  `[question]` — never a blocker asserting a hazard nobody rendered. Check
+  rolling-deploy ordering for DROP COLUMN / NOT NULL adds (old pods still run
+  the old schema mid-rollout).
+  **Migration naming/order — P1 ONLY when out of order with the base
+  branch**: if the PR adds a migration that the repo's migration tool orders
+  (by a sequence number, a timestamp, or a declared parent), verify it against
+  the **base branch**: its number must not already exist there, and its
+  declared parent must be the base branch's current head for that migration
+  set — out of sequence with the base branch (the migration tool would break
+  on merge) is P1. Number overlaps with other still-open PRs are **NOT
+  findings** — at most one `nit` note listing the PR numbers (whoever merges
+  second renumbers; that is routine).
+- **Blast radius sizing** — judge fan-out against **production row counts, not
+  the diff**. Any new/changed scheduled job, recovery cron, backfill, or
+  redispatch that does work per matching row needs a per-run cap with
+  deterministic ordering and a kill switch, and a predicate that is bounded;
+  missing any of these is P1. The current production count of rows matching
+  the trigger predicate is the author's to state: when the PR body does not,
+  ask for it in a `[question]` (an accumulated backlog is the payload of the
+  first tick). Review the **first tick over the accumulated backlog**, not the
+  steady state.
+- **Backfill-vs-validator proof** — any migration/backfill copying legacy data
+  into a newly validated field needs the count of nonconforming source rows;
+  "the data will fit the new pattern" is a claim. When the PR does not state
+  the count, ask the author for it in a `[question]`.
+
+## MIGRATION GATE (when the task string flags it)
+
+Judge on the same readable evidence. The ONLY ordering blocker is being out of
+order with the **base branch**. Report `gate: unproven` in your findings block,
+with the `[question]` that would settle it, unless the migration is readably
+metadata-only on a small table, in sequence with the base branch,
+backfill-free, and rolling-deploy ordering-safe — only in that narrow case
+report `gate: self-verdict-ok`.

package/assets/seeds/agents/pass-delivery.md

@@ -0,0 +1,37 @@
+---
+name: pass-delivery
+description: Delivery-semantics review pass — at-least-once handlers, redelivery, drop paths, fetch windows.
+tools: read, bash, grep, glob
+---
+
+{{include:prompts/pass-common.md}}
+
+# Lens: delivery semantics (at-least-once)
+
+Apply to: webhook handlers, background tasks, message-queue and task-queue
+consumers, crons, retries.
+
+Queues, task services, webhooks, and crons deliver at least once; review
+handlers **resume-point-by-resume-point, not statement-by-statement**.
+
+- **Redelivery sweep**: enumerate every database, index or external write reachable
+  from the task entrypoint and ask for each: *process killed immediately after
+  this statement, task redelivered from the top — does it raise, duplicate, or
+  converge?* Every insert into a unique/OneToOne-constrained table must be
+  conflict-safe (`ignore_conflicts`, upsert, `get_or_create`) or
+  transactionally grouped. If the PR claims "retry-safe", the sweep covers the
+  **whole task**, not only the statement that last crashed.
+- **Drop-path enumeration**: wherever a handler consumes its only delivery (a
+  `cache.add` dedup key, an ACK, a cursor advance), list every exit path
+  (`return`, `raise`, early guard) between that consumption and durable
+  completion of the work — each one is a permanent message-loss path requiring
+  individual justification, or the consumption must move after completion.
+  Converting an error exit into a silent success (`raise` → `return`, NACK →
+  ACK) demands a line-level trace of what durable state was already consumed
+  at that point; verify any claimed compensating read by its **position in the
+  control flow**, not by plausibility.
+- **Fetch-window completeness**: when post-race correctness relies on a later
+  read "covering" earlier events, check the read's window semantics under
+  every ordering of {event arrival, boundary-advancing write, read} — a window
+  keyed to a moving boundary structurally cannot return events that land
+  behind it.