@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-runtime-typeof.yml

@@ -0,0 +1,121 @@
+id: no-runtime-typeof
+language: TypeScript
+severity: hint
+message: "Runtime 'typeof' check — decode/parse the value at its I/O boundary, then branch on the domain value"
+note: |
+  Adapted from dmmulroy/anti-slop's `no-runtime-typeof`
+  (src/rules/no-runtime-typeof.ts, MIT). Upstream's own
+  `allowInTypeGuards` option only exempts a `typeof` sitting inside a
+  function whose return type is a type predicate (`x is T`) — the 2026-
+  08-19 audit found that option alone doesn't rescue the rule for this
+  codebase (73 predicate functions out of 404 client hits), so this
+  port adds two more exemptions, informed by where the audit found the
+  remaining hits actually concentrated: third-party JSON/LSP wire
+  payloads decoded inside functions already named for that job
+  (`trivy-client.ts`, `lsp/client.ts`, `git-guard.ts`).
+
+  Exemptions (all three must miss for a hit to fire):
+  1. `typeof` inside a function whose OWN return type is a type
+     predicate (`x is T`) — upstream's `allowInTypeGuards`.
+  2. `typeof` inside a function/method whose name starts with
+     `parse`, `decode`, `validate`, `is`, or `assert` — these are this
+     codebase's own naming convention for a boundary-parsing or
+     predicate function (`asRecord`, `errorMessage`), even when
+     TypeScript's `is`-predicate return-type syntax isn't used.
+  3. `.d.ts` files — declaration files have no runtime, so a `typeof`
+     there is a type query, not a check (the language keeps these
+     syntactically distinct in tree-sitter, but this glob is cheap
+     insurance).
+
+  These exemptions are structural, not semantic: they check the
+  ENCLOSING function's name/return-type, not what the `typeof` result
+  is actually used for, so a mis-named function (a real boundary
+  parser not named `parse*`, or a `checkFoo` predicate) still fires,
+  and a `parse*`-named function with an unrelated internal `typeof`
+  check is still exempted. `stopBy: end` searches to the nearest
+  enclosing function of that shape at ANY depth, which also exempts a
+  `typeof` inside a nested non-guard closure defined inside a guard —
+  a conservative (under-fires, not over-fires) choice.
+
+  Shipped at `hint`: the 2026-08-19 audit rejected outright adopting
+  this rule against pi-lens's own tree — it has no schema-decoding
+  library, and the concentration of hits is exactly where the rule
+  wants a schema layer (third-party JSON/LSP wire payloads), so
+  self-conformance would be an architecture decision, not a lint fix.
+  That verdict stands for pi-lens's own code; it doesn't mean the
+  pattern has no value for a repository that DOES have a decoder at its
+  boundaries. Self-scan note: do NOT try to make pi-lens's own tree
+  clean against this rule (#1718's baseline problem, likely never, per
+  the architecture-decision finding above); the adopting PR records the
+  2026-08-19 hit count so a rule that fires thousands of times against
+  its own product's source gets its pattern tightened before anyone
+  trusts the count on a real target repo.
+
+  2026-08-20 (refs #1727, #1777): CONSIDERED for promotion to `error`,
+  KEPT at `hint`. Four-corpus census, ast-grep CLI 0.45, with the three
+  exemptions above already applied:
+
+  | corpus | hits |
+  |---|---:|
+  | pi-lens `clients/` | 257 |
+  | pi-lens `tests/` | 232 |
+  | pi core `packages/` | 543 (431 outside test paths) |
+  | opencode `packages/` | 1122 (991) |
+  | oh-my-pi `packages/` | 4114 (3239) |
+
+  Verdict: the highest-volume rule in the whole catalog, and the volume is
+  not noise — it is the finding the note already records, that a codebase
+  without a decoding layer answers this rule with an architecture change.
+  The suppression the maintainer's own framing asks for ("suppress a
+  `typeof` whose checked binding comes from a source typed `unknown`")
+  needs the binding's declared type, which is type information ast-grep
+  does not have; the three exemptions here are the closest structural
+  approximation and they still leave 3,239 hits on one corpus. Promoting
+  at this volume would block agent turns across every one of these trees.
+ignores:
+  - "**/*.d.ts"
+rule:
+  kind: unary_expression
+  pattern: typeof $X
+  not:
+    any:
+      - inside:
+          stopBy: end
+          any:
+            - kind: function_declaration
+            - kind: function_expression
+            - kind: arrow_function
+            - kind: method_definition
+          has:
+            stopBy: neighbor
+            kind: type_annotation
+            has:
+              stopBy: neighbor
+              kind: type_predicate
+      - inside:
+          stopBy: end
+          kind: function_declaration
+          has:
+            stopBy: neighbor
+            kind: identifier
+            regex: '^(parse|decode|validate|is|assert)'
+      - inside:
+          stopBy: end
+          kind: function_expression
+          has:
+            stopBy: neighbor
+            kind: identifier
+            regex: '^(parse|decode|validate|is|assert)'
+      - inside:
+          stopBy: end
+          kind: method_definition
+          has:
+            stopBy: neighbor
+            kind: property_identifier
+            regex: '^(parse|decode|validate|is|assert)'
+      - inside:
+          stopBy: end
+          kind: variable_declarator
+          all:
+            - has: { stopBy: neighbor, kind: identifier, regex: '^(parse|decode|validate|is|assert)' }
+            - has: { stopBy: neighbor, kind: arrow_function }

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-server-bind-wildcard.yml

@@ -9,14 +9,26 @@ note: |
   network interface, including public ones. Production servers
   should bind to a specific interface or use a reverse proxy.
 
-  Matches any `call` node whose text contains `host=` followed
-  by `0.0.0.0` (within a few characters). Note: `0.0.0.0` in
-  `app.run()` (Flask dev server) is also flagged — for
-  development, prefer `127.0.0.1`.
+  Matches any `call` node whose text contains `host=` followed by
+  `0.0.0.0` (within a few characters). Note: `0.0.0.0` in `app.run()`
+  (Flask dev server) is also flagged — for development, prefer
+  `127.0.0.1`.
 
-  Style: regex on the call node's text. The pattern doesn't
-  anchor at start (the call has the function name first, e.g.
-  `app.run(`); the regex matches anywhere in the call text.
+  2026-08-20 (review round, refs #1806): a prior fix anchored this to
+  `.run(...)` / `.listen(...)` / `.serve(...)` call targets specifically,
+  to exclude a pydantic `Settings.model_construct(...)` test fixture
+  that happened to have a `host`-named field set to `"0.0.0.0"`. That
+  traded one false positive for a false-negative CLASS: a bare
+  `run(host='0.0.0.0')` (no receiver), `uvicorn.Config(app,
+  host='0.0.0.0')` (a different call name — the config object, not the
+  `.run()` invocation), and `app.run_server(...)` (a different method
+  name) all went invisible. For a BLOCKER-severity security rule, a
+  rare false positive is the acceptable trade, not a missed detection
+  class — reverted to the broad `kind: call` + regex match, and
+  excluded the SPECIFIC false-positive shape instead: a call to
+  `.model_construct(...)` / `.construct(...)` (pydantic's
+  validation-skipping constructors — the "this builds a config object,
+  it doesn't bind a socket" case the FP actually was).
 
   The regex uses `.{0,5}` between `host` and `0.0.0.0` to
   accept either `host='0.0.0.0'` (single quote) or
@@ -26,3 +38,7 @@ metadata:
 rule:
   kind: call
   regex: 'host.{0,5}0\.0\.0\.0'
+  not:
+    any:
+      - pattern: $X.model_construct($$$ARGS)
+      - pattern: $X.construct($$$ARGS)

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-shape-in-symbol-names.yml

@@ -0,0 +1,68 @@
+id: no-shape-in-symbol-names
+language: TypeScript
+severity: hint
+message: "Symbol name contains 'shape' — name it for its domain role, not its structure"
+note: |
+  Adapted from dmmulroy/anti-slop's `no-shape-in-symbol-names`
+  (src/rules/no-shape-in-symbol-names.ts, MIT). Upstream bans the
+  case-insensitive substring "shape" in every identifier, private
+  identifier, and JSX identifier: "shape" describes the STRUCTURE of a
+  value, not what it MEANS, and a name that only says "this has some
+  shape" (`PackageJsonShape`, `windowsShaped`) is filler a domain term
+  would replace (`PackageJsonManifest`, `usesWindowsSeparators`).
+
+  Explicitly NOT self-applied: AGENTS.md's own "Recurring defect shapes"
+  catalog uses "shape" as load-bearing review vocabulary, and pi-lens's
+  own code mirrors it — `ProbeFailureShape`, `windowsShaped`,
+  `basenameForShape`, 27 distinct identifiers / 291 occurrences in the
+  2026-08-19 audit. Banning the word in THIS repo would fight the
+  convention its own review process runs on. That is a reason not to
+  wire this rule into pi-lens's self-scan (#1718's decision to make),
+  not a reason to withhold it from the catalog — a repo without that
+  convention gets real signal from it. Self-scan note: do NOT try to
+  make pi-lens's own tree clean against this rule; the adopting PR
+  records the 2026-08-19 hit count instead.
+
+  Scope: `identifier`, `property_identifier`, `private_property_identifier`,
+  and `type_identifier` nodes whose text contains "shape"
+  case-insensitively, anywhere in the name (matches upstream's
+  substring semantics, so `reshape`/`Shapeless` are in scope too, not
+  just whole-word `shape`). `jsx_identifier` is dropped — this repo
+  ships no `.tsx`, so it has nothing to match (same call as
+  `no-unknown-laundering.yml`'s "no JS variant" note).
+
+  2026-08-20 (refs #1727, #1777): CONSIDERED for promotion to `error`,
+  KEPT at `hint`. Four-corpus census, ast-grep CLI 0.45:
+
+  | corpus | hits |
+  |---|---:|
+  | pi-lens `clients/` | 48 (13 distinct identifiers) |
+  | pi-lens `tests/` | 140 |
+  | pi core `packages/` | 5 (5 outside test paths, 1 file) |
+  | opencode `packages/` | 88 (76) |
+  | oh-my-pi `packages/` | 837 (608, 65 files) |
+
+  Verdict: structural scoping was applied and was not enough. Excluding
+  test paths — the mechanism this catalog now uses for
+  `require-safety-comment-for-as-unknown-as.yml` — removes pi-lens's 140
+  `tests/` hits and leaves all 48 `clients/` hits, because they are not a
+  test idiom. They are 13 production identifiers, several of them the
+  review vocabulary this repo runs on (`ProbeFailureShape`,
+  `basenameForShape`, `windowsShaped`, `checkManifestShape`,
+  `validateInputShape`) and one that is upstream's own headline example
+  (`PackageJsonShape`). The only ways to zero are an allowlist of pi-lens
+  identifiers baked into a rule that ships to other repositories — a
+  hand-maintained parallel list, which AGENTS.md forbids — or renaming 13
+  exported production symbols, which is a refactor with its own blast
+  radius and its own issue, not a severity change. Left at `hint` and
+  still NOT tagged for the self-scan.
+rule:
+  any:
+    - kind: identifier
+      regex: "(?i)shape"
+    - kind: property_identifier
+      regex: "(?i)shape"
+    - kind: private_property_identifier
+      regex: "(?i)shape"
+    - kind: type_identifier
+      regex: "(?i)shape"

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-sql-in-code-js.yml

@@ -3,8 +3,9 @@ language: JavaScript
 message: "Raw SQL string in code — use query builder or ORM"
 severity: error
 note: |
-  Raw SQL strings are error-prone and hard to maintain.
-  Use a query builder (knex, drizzle) or ORM (prisma, typeorm).
+  Raw SQL strings built via concatenation or template substitution are
+  error-prone and open to injection. Use a query builder (knex, drizzle)
+  or ORM (prisma, typeorm), or pass the value as a bind parameter.
   The `, $$$REST` suffix matches the optional parameters/options
   argument common to ORM `query()`/`execute()` signatures. Without
   it, only the 1-arg form (no params) matches.
@@ -12,6 +13,27 @@ note: |
   because the SQL literal lives 2 levels below the call_expression
   (inside `arguments`); the default `has` neighbor doesn't drill
   that deep.
+
+  `$SQL` is constrained to a `binary_expression` (string concatenation,
+  e.g. `"SELECT ... " + id`) or a template string with at least one
+  `${...}` substitution — the two shapes that actually interpolate a
+  runtime value into the query text. A plain string literal (even one
+  containing a `?` placeholder passed alongside a params array — the
+  parameterized-query idiom) is NOT flagged: the query text itself is
+  static, so there's nothing to inject. Before this constraint, EVERY
+  `db.query("<literal SQL>")` call matched regardless of how the value
+  was passed, which is why the shipped rule produced 261 hits on a
+  correctly-parameterized DB layer (#1806 audit). Mirrors the Python
+  sibling `no-python-sql-string-concat`, which already restricted to
+  `binary_operator` concatenation.
+
+  2026-08-20 (review round, refs #1806, low-severity finding): a
+  `binary_expression` where BOTH sides are string literals
+  (`"SELECT * FROM " + "users"`) is compile-time-constant text, not
+  runtime interpolation — nothing to inject. Excluded via a `has:
+  field: left/right, kind: string` check on both operands. A
+  literal-plus-variable concatenation (the actual injection shape)
+  still flags.
 rule:
   all:
     - any:
@@ -22,3 +44,20 @@ rule:
         regex: >-
           (?i)(SELECT|INSERT|UPDATE|DELETE|CREATE TABLE|DROP TABLE|ALTER
           TABLE)
+constraints:
+  SQL:
+    any:
+      - all:
+          - kind: binary_expression
+          - not:
+              all:
+                - has:
+                    field: left
+                    kind: string
+                - has:
+                    field: right
+                    kind: string
+      - all:
+          - kind: template_string
+          - has:
+              kind: template_substitution

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-sql-in-code.yml

@@ -3,8 +3,9 @@ language: TypeScript
 message: "Raw SQL string in code — use query builder or ORM"
 severity: error
 note: |
-  Raw SQL strings are error-prone and hard to maintain.
-  Use a query builder (knex, drizzle) or ORM (prisma, typeorm).
+  Raw SQL strings built via concatenation or template substitution are
+  error-prone and open to injection. Use a query builder (knex, drizzle)
+  or ORM (prisma, typeorm), or pass the value as a bind parameter.
   The `, $$$REST` suffix matches the optional parameters/options
   argument common to ORM `query()`/`execute()` signatures. Without
   it, only the 1-arg form (no params) matches.
@@ -12,6 +13,27 @@ note: |
   because the SQL literal lives 2 levels below the call_expression
   (inside `arguments`); the default `has` neighbor doesn't drill
   that deep.
+
+  `$SQL` is constrained to a `binary_expression` (string concatenation,
+  e.g. `"SELECT ... " + id`) or a template string with at least one
+  `${...}` substitution — the two shapes that actually interpolate a
+  runtime value into the query text. A plain string literal (even one
+  containing a `?` placeholder passed alongside a params array — the
+  parameterized-query idiom) is NOT flagged: the query text itself is
+  static, so there's nothing to inject. Before this constraint, EVERY
+  `db.query("<literal SQL>")` call matched regardless of how the value
+  was passed, which is why the shipped rule produced 261 hits on a
+  correctly-parameterized DB layer (#1806 audit). Mirrors the Python
+  sibling `no-python-sql-string-concat`, which already restricted to
+  `binary_operator` concatenation.
+
+  2026-08-20 (review round, refs #1806, low-severity finding): a
+  `binary_expression` where BOTH sides are string literals
+  (`"SELECT * FROM " + "users"`) is compile-time-constant text, not
+  runtime interpolation — nothing to inject. Excluded via a `has:
+  field: left/right, kind: string` check on both operands. A
+  literal-plus-variable concatenation (the actual injection shape)
+  still flags.
 rule:
   all:
     - any:
@@ -22,3 +44,20 @@ rule:
         regex: >-
           (?i)(SELECT|INSERT|UPDATE|DELETE|CREATE TABLE|DROP TABLE|ALTER
           TABLE)
+constraints:
+  SQL:
+    any:
+      - all:
+          - kind: binary_expression
+          - not:
+              all:
+                - has:
+                    field: left
+                    kind: string
+                - has:
+                    field: right
+                    kind: string
+      - all:
+          - kind: template_string
+          - has:
+              kind: template_substitution

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-unknown-laundering.yml

@@ -1,7 +1,9 @@
 id: no-unknown-laundering
 language: TypeScript
-severity: warning
+severity: error
 message: "type alias to bare 'unknown' — give the alias real shape or inline 'unknown' at the one call site that needs it"
+metadata:
+  category: pi-lens-self-scan
 note: |
   `type X = unknown` adds a name but zero type information — every
   consumer of X still has to narrow from scratch, so the alias only
@@ -23,5 +25,8 @@ note: |
   forces the caller to narrow — so it is not syntactically distinguishable
   from a laundered one; only `type X = unknown` stayed a reliable
   precision signal (zero hits in the same scan).
+
+  2026-08-20 (refs #1856): PROMOTED from `warning` to `error` after a
+  fresh scan confirmed zero hits in pi-lens's own tree.
 rule:
   pattern: "type $T = unknown"

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-unknown-parameters.yml

@@ -0,0 +1,67 @@
+id: no-unknown-parameters
+language: TypeScript
+severity: hint
+message: "Parameter typed 'unknown' — decode it at the I/O boundary instead of leaving it unparsed"
+note: |
+  Adapted from dmmulroy/anti-slop's `no-unknown-parameters`
+  (src/rules/no-unknown-parameters.ts, MIT). Upstream exempts a
+  parameter literally named `cause` (the standard `Error` cause-chain
+  field, which is `unknown` by the language's own `ErrorOptions` type)
+  — kept here for the same reason.
+
+  Shipped at `hint`, not `error`: AGENTS.md smell 3 records that this
+  exact arm was dropped from `no-unknown-laundering.yml` after an
+  FP-scan found 166 legitimate `unknown` parameters in pi-lens's own
+  tree (type-guard/validator functions like
+  `errorMessage(err: unknown)`). That finding is about THIS repo's own
+  code, not a reason to withhold the pattern from the shipped catalog —
+  other repositories may have real slop here — so it ships as a
+  discoverable hint instead. Self-scan note: do NOT try to make
+  pi-lens's own tree clean against this rule (#1718's baseline
+  problem); the adopting PR records the 2026-08-19 hit count instead.
+
+  Scope: a direct `unknown` annotation on a required or optional
+  parameter, matched structurally at the `predefined_type` leaf (same
+  shape as `no-bare-object-param.yml`). Rest/default-value parameters
+  (`...rest: unknown[]`, `x = y: unknown`) are out of scope — ast-grep
+  doesn't unwrap those parameter-pattern wrappers the way upstream's
+  AST-walk does. A union member (`unknown | null`) is not flagged for
+  the same "direct annotation only" reason `no-bare-object-param.yml`
+  gives.
+
+  2026-08-20 (refs #1727, #1777): CONSIDERED for promotion to `error`,
+  KEPT at `hint`. Four-corpus census, ast-grep CLI 0.45:
+
+  | corpus | hits |
+  |---|---:|
+  | pi-lens `clients/` | 149 |
+  | pi-lens `tests/` | 146 |
+  | pi core `packages/` | 381 (194 outside test paths) |
+  | opencode `packages/` | 678 (522) |
+  | oh-my-pi `packages/` | 2140 (1697) |
+
+  Verdict: structural narrowing was probed and does not reach zero. The
+  type-guard suppression (a parameter inside a function whose return type
+  is a `value is T` predicate) and a parser-name suppression together
+  clear the large predicate/validator block, but the residual is a second
+  legitimate class they cannot touch: opaque-payload SINKS that never
+  parse their argument at all — `setFileFact(path, id, value: unknown)`,
+  `bus(channel, payload: unknown)`, `emitLensEvent(name, payload:
+  unknown)`, `(err: unknown) => …` rejection handlers. `unknown` is the
+  CORRECT parameter type there, and it is syntactically identical to the
+  unparsed-boundary case the rule targets.
+rule:
+  kind: predefined_type
+  regex: "^unknown$"
+  inside:
+    kind: type_annotation
+    inside:
+      all:
+        - any:
+            - kind: required_parameter
+            - kind: optional_parameter
+        - not:
+            has:
+              stopBy: neighbor
+              kind: identifier
+              regex: "^cause$"

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-unknown-returns.yml

@@ -0,0 +1,106 @@
+id: no-unknown-returns
+language: TypeScript
+severity: error
+message: "Function returns 'unknown' — parse the value at its boundary and return a named domain type"
+metadata:
+  category: pi-lens-self-scan
+note: |
+  Adapted from dmmulroy/anti-slop's `no-unknown-returns`
+  (src/rules/no-unknown-returns.ts, MIT). Upstream also resolves
+  `Promise<unknown>` and same-file type aliases that resolve to
+  `unknown`; both are dropped here — same-file alias/generic resolution
+  is out of ast-grep's reach (the `no-bare-object-param.yml` precedent).
+
+  Shipped at `hint`, not `error`: AGENTS.md smell 3 records that this
+  arm was dropped from `no-unknown-laundering.yml` after an FP-scan
+  found 192 legitimate `unknown` return types in pi-lens's own tree
+  (parsers, and a `ProxyHandler.get` trap whose signature TypeScript
+  itself requires). That's a finding about this repo's own code, not a
+  reason to withhold the pattern from the catalog, so it ships as a
+  discoverable hint. Self-scan note: do NOT try to make pi-lens's own
+  tree clean against this rule (#1718's baseline problem); the adopting
+  PR records the 2026-08-19 hit count instead.
+
+  Scope: a direct `unknown` return-type annotation, matched
+  structurally. Most function-like nodes wrap their return type in a
+  `type_annotation` node that is a DIRECT child of the function node
+  (function declaration/expression, arrow function, method signature/
+  definition, call/construct signature) — that is exactly the
+  return-type position; a parameter's `type_annotation` is nested one
+  level deeper, inside `required_parameter`/`optional_parameter`, so
+  the two never collide. `function_type` (`(x: T) => R`, used in
+  function-type aliases) was the one exception in
+  tree-sitter-typescript's grammar: its return type sits directly after
+  `=>` with no `type_annotation` wrapper at all, so it needed its own
+  branch. The #1824 scope correction removed that branch because callback
+  result types describe what callers consume, not an unparsed value crossing
+  a boundary. See the 2026-08-20 #1824 entry below for why that branch is
+  now gone.
+
+  2026-08-20 (refs #1727, #1777): CONSIDERED for promotion to `error`,
+  KEPT at `hint`. Four-corpus census, ast-grep CLI 0.45:
+
+  | corpus | hits |
+  |---|---:|
+  | pi-lens `clients/` | 19 |
+  | pi-lens `tests/` | 58 |
+  | pi core `packages/` | 17 (14 outside test paths) |
+  | opencode `packages/` | 111 (105) |
+  | oh-my-pi `packages/` | 288 (226) |
+
+  Verdict: the closest of the six to promotable, and still not there. A
+  probed narrowing — drop the `function_type` arm (a callback TYPE
+  declaring `=> unknown` says "the caller ignores my result", not "a
+  boundary went unparsed") plus a parser-name suppression — takes pi-lens
+  from 77 hits to 16, and `clients/` from 19 to 3. The residual 3 are
+  generic pass-through wrappers (`clients/extension-log.ts`'s console
+  capture and proxy wrapper) whose return value genuinely IS the wrapped
+  function's, so `unknown` is correct. Reaching zero needed a third
+  suppression shaped around those three sites specifically, which is
+  overfitting to one tree, so nothing was changed here. The
+  `function_type` scope question is worth its own issue on its own merits;
+  it is a scope correction, not a tier change, and this PR does not make
+  it.
+
+  2026-08-20 (#1824, refs #1727, #1815, review round 1 N4): dropped
+  the `function_type` arm named above. A TYPE-POSITION `unknown`
+  return is a legitimate contract ("the caller ignores my result"),
+  not a value-position return that skipped parsing at a boundary. This
+  is a scope correction, not a severity change. Same scan setup,
+   before → after: pi-lens full tree 79 → 23; pi-lens `clients/` +
+   `index.ts` 21 → 9 (see the adopting PR for the four-corpus
+   before/after on the same narrow scope). The value-position arm below
+   is unchanged and is what the rule now exclusively targets.
+  2026-08-20 (refs #1856): PROMOTED from `hint` to `error` after the
+  remaining value-position returns were given named domain types or made
+  generic so their pass-through contract stays exact. The pi-lens
+  self-scan is clean at promotion time.
+  Test paths stay excluded: mocks and interleaving controls intentionally
+  return opaque sentinel values, while this rule governs production
+  boundaries whose domain shape is knowable.
+ignores:
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.test.mts"
+  - "**/*.test.cts"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+  - "**/tests/**"
+  - "**/test/**"
+  - "**/__tests__/**"
+rule:
+  kind: predefined_type
+  regex: "^unknown$"
+  inside:
+    kind: type_annotation
+    inside:
+      any:
+        - kind: function_declaration
+        - kind: function_expression
+        - kind: generator_function_declaration
+        - kind: arrow_function
+        - kind: method_signature
+        - kind: method_definition
+        - kind: construct_signature
+        - kind: constructor_type
+        - kind: call_signature

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-unsafe-dictionary-any.yml

@@ -0,0 +1,50 @@
+id: no-unsafe-dictionary-any
+language: TypeScript
+severity: error
+metadata:
+  category: pi-lens-self-scan
+message: "Record<K, any> — the value type gives callers no contract; use Record<K, unknown> or a real value type"
+note: |
+  Adapted from dmmulroy/anti-slop's `no-unsafe-dictionary-type`
+  (src/rules/no-unsafe-dictionary-type.ts, MIT), narrowed to the `any`
+  arm only. Upstream also flags `unknown`, bare `object`, `{}`, and
+  unions/aliases that resolve to one of those — this port drops all of
+  that (see the `no-unsafe-dictionary-unknown.yml` sibling for the
+  `unknown` arm, shipped separately at `hint`). `Record<K, any>` is the
+  one arm this repo's own FP scan (AGENTS.md smell 3) found ZERO
+  legitimate uses for: `any` as a dictionary's value type doesn't just
+  widen, it turns off checking for every property read off that
+  dictionary, which `unknown` does not do.
+
+  Scope: a direct `Record<$K, any>` type reference, matched
+  structurally — the same "direct annotation only" cut as
+  `no-bare-object-param.yml`. Upstream's alias-resolution and
+  type-literal-index-signature arms (`{ [key: string]: any }`,
+  an alias that resolves to `Record<string, any>`) are dropped for the
+  same reason: same-file symbol/generic resolution ast-grep doesn't do.
+
+  FP-scan (napi engine, clients/ + tests/, 2026-08-19): 4 hits, not the
+  2 the original audit measured — the audit's grep missed two test
+  files. `clients/cache/rule-cache.ts:81` and
+  `clients/tree-sitter-query-loader.ts:129` are genuine dictionary
+  value-type contracts (`post_filter_params?: Record<string, any>` on
+  loaded query metadata) and are fixed in the same PR to
+  `Record<string, unknown>` — every consumer already narrows manually
+  (`clients/tree-sitter-client.ts` takes `postFilterParams?: unknown`
+  or `any` as a local parameter type at the point it's actually
+  destructured, never relies on the interface field being `any`).
+  `tests/clients/call-graph.test.ts:736` and
+  `tests/tools/lens-diagnostics.test.ts:198` are a different shape:
+  ad-hoc mutation/access of a raw JSON fixture object
+  (`raw.edges[0].evidenceKind = "..."`, `props.mode.enum`) across
+  several unrelated nested paths, where `unknown` would require a cast
+  at every access and buys nothing — the same "test fixture shaping"
+  class already exempted for `require-safety-comment` and the empty-
+  object-spread hint. Excluded by path rather than fixed.
+ignores:
+  - "**/tests/clients/call-graph.test.ts"
+  - "**/tests/tools/lens-diagnostics.test.ts"
+rule:
+  pattern:
+    context: "type T = Record<$K, any>;"
+    selector: generic_type

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-unsafe-dictionary-unknown.yml

@@ -0,0 +1,56 @@
+id: no-unsafe-dictionary-unknown
+language: TypeScript
+severity: hint
+message: "Record<K, unknown> — every read still needs a runtime narrow; prefer a real value type where the shape is known"
+note: |
+  Adapted from dmmulroy/anti-slop's `no-unsafe-dictionary-type`
+  (src/rules/no-unsafe-dictionary-type.ts, MIT), narrowed to the
+  `unknown` arm — the sibling of `no-unsafe-dictionary-any.yml`, which
+  covers the `any` arm at `error`.
+
+  Shipped at `hint`, not `error` or `warning`: AGENTS.md smell 3
+  already records that `Record<string, unknown>` dictionaries are the
+  CORRECT, idiomatic contract at this repo's own validator/parser/
+  telemetry/metadata boundaries (9+ legitimate hits in the original
+  FP scan that got the wider `no-unknown-laundering` fan-out dropped
+  down to the alias-only arm). That finding doesn't generalize to every
+  repository this catalog ships to, so the pattern stays in the catalog
+  as a discoverable hint — "here's every open dictionary whose value
+  type forces the caller to narrow before use, go look and decide" —
+  rather than a rule that tells this repo's own idiom it's wrong.
+
+  Self-scan note: do NOT try to make pi-lens's own tree clean against
+  this rule (that is #1718's baseline problem, not this PR's). Recorded
+  in the adopting PR body per rule instead: 2026-08-19 hit count on
+  clients/ + tests/, napi engine.
+
+  Scope: same direct-annotation cut as the `any` arm — a `Record<$K,
+  unknown>` type reference, matched structurally. Alias resolution and
+  type-literal index signatures are out of scope for the same reason.
+
+  2026-08-20 (refs #1727, #1777): CONSIDERED for promotion to `error`,
+  KEPT at `hint`. Four-corpus census, ast-grep CLI 0.45:
+
+  | corpus | hits |
+  |---|---:|
+  | pi-lens `clients/` | 142 |
+  | pi-lens `tests/` | 247 |
+  | pi core `packages/` | 299 (162 outside test paths) |
+  | opencode `packages/` | 533 (392) |
+  | oh-my-pi `packages/` | 2994 (1727) |
+
+  Verdict: promoting this rule would contradict AGENTS.md's own written
+  guidance in the same repository. Smell 3 records `Record<string,
+  unknown>` as the CORRECT contract at this codebase's validator, parser,
+  telemetry, and metadata boundaries. The suppression that would rescue it
+  — "suppress when the enclosing scope narrows the value before use" —
+  needs data flow from the dictionary's declaration to each read, which
+  ast-grep's structural matcher does not do; a syntactic stand-in would be
+  the vacuous guard this repo's review process screens for. The `any` arm
+  (`no-unsafe-dictionary-any.yml`) stays the error-tier member of the
+  pair, and it is clean on pi-lens: `any` turns checking OFF for every
+  property read, which is the discriminator `unknown` does not share.
+rule:
+  pattern:
+    context: "type T = Record<$K, unknown>;"
+    selector: generic_type

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-win32-isabsolute-for-qualification.yml

@@ -1,6 +1,8 @@
 id: no-win32-isabsolute-for-qualification
 language: TypeScript
 severity: warning
+metadata:
+  category: pi-lens-self-scan
 message: "Use isFullyQualified for path qualification instead of win32.isAbsolute"
 note: |
   Qualification must follow the input path's shape. Use clients/path-utils.ts