Unparsed primitive types throughout the codebase obscure domain semantics and defeat static analysis

[ooloth]

Problem 🎯

Data flows through the system as bare primitives — dict, list[dict], str, int — long after crossing I/O boundaries where it could be parsed into meaningful domain types. Examples:

• GitHub issue data: open_autonomous_issues(), open_issues(), post_issues(), issue_context(), _apply_verdict() all pass dict / list[dict]. The actual shape (which keys exist, their types) is implicit — determined by --json field lists passed to gh and by conventions in the scan/groom loops.
• Agent step output: step() returns dict. The JSON schema is defined in prompts but invisible to the type system. Callers access raw["findings"], clustered["clusters"], reviewed["ready"] etc. with no static checking.
• Project/scan config: load_project() returns dict, scan blocks are dict, fields like project["repo"] and scan["type"] are untyped strings.
• Identifiers and paths: project IDs, scan types, issue numbers, branch names, labels — all bare str / int with no domain wrapper to distinguish them or constrain their values.
• Run metadata: the metadata dict built in scan/fix/groom finales is assembled ad-hoc with string keys.

In practice this mostly works — the codebase is small and conventions are consistent. But it means:

• Key typos and shape mismatches are silent at type-check time
• You have to trace through I/O call sites to know what a value actually contains
• Functions that need different subsets of fields share the same dict type
• Domain rules (e.g. "a scan type is one of these known strings") live in runtime checks or conventions, not in the type system

Definition of done ✅

• I/O boundaries (GitHub API responses, agent step JSON output, project config loading, run metadata) parse into explicit domain types on entry — you know this is fixed when ty check catches a misspelled key, missing field, or wrong type at any call site
• Internal code works with validated, meaningfully labeled data — not raw dicts and strings
• The approach is chosen deliberately between TypedDicts, dataclasses, Pydantic, NewType, enums, etc. based on the tradeoffs at each boundary: JSON passthrough vs validated parsing vs runtime construction vs lightweight semantic tagging

Out of scope ⛔

• Typing the gh() wrapper itself (it returns CompletedProcess, which is fine)
• Typing third-party library internals
• Changing the JSON schemas in agent prompts — this is about parsing what already exists, not redesigning the agent protocol

[ooloth]

Related issues

• config: replace hand-authored projects.schema.json with Pydantic models #27 — config: replace hand-authored projects.schema.json with Pydantic models (directly overlapping — Pydantic for the config boundary)
• errors: all failure modes raise RuntimeError with no type distinction #42 — errors: all failure modes raise RuntimeError with no type distinction (same theme — untyped primitives at error boundaries)
• Missing required project config keys raise KeyError far from load site #6 — Missing required project config keys raise KeyError far from load site (symptom of untyped config dicts)

[ooloth]

The new dedup step (from #39) adds two more instances of this pattern:

• open_issues() in github.py returns list[dict] — the shape is {number: int, title: str, body: str} but only documented in the --json argument string
• _dispatch_dedup_actions() in scan.py takes list[dict] — the shape varies by action type (post has title/body/label, comment has target_issue/comment_body/reason, skip has title/reason) but all are untyped dicts