Using Static Analysis Engineering

Using Static Analysis Engineering

Overview

A static analyzer is an engine: AST → abstract domain → fixed-point inference → verdict. Treat it as one, or your "linter" calcifies into a pile of regexes that nobody trusts.

This pack treats building an analyzer as a discipline distinct from running one. A real analyzer has a chosen visitation strategy (visitor, walker, transformer), an abstract domain it computes over (a lattice with defined join semantics, monotonicity, and finite height), a phased inference pipeline that terminates because the lattice does, an extension surface that allows new rules without forking the engine, and an honest economics for false positives — because the rate at which suppressions accumulate determines whether the analyzer is load-bearing or ceremonial five years from now.

This is the producer-side counterpart to architecture analysis:

• axiom-system-archaeologist consumes analyzers — runs existing tools, ingests their findings, and synthesises a system map. The analyzer is an oracle; the archaeologist is its reader.
• axiom-static-analysis-engineering (this pack) builds analyzers — designs the AST visitor, the abstract domain, the inference order, the rule plugin model, and the suppression discipline. The analyzer is the artifact; the engineer is its author.
• The two pair: an archaeologist that finds a gap in coverage hands the gap to this pack; this pack ships the new rule; the archaeologist re-runs and the gap closes. Cross-link, don't duplicate.

There is a third member of this family, split by what the tool produces rather than by what it reads:

• axiom-tensor-compiler-engineering transforms IR and produces executables. This pack reads a program and emits a verdict about it; that pack rewrites a program and emits something that runs. The disciplines rhyme — both need a defined IR, both need an extension model, both live or die on trust in their output — but the trust mechanism differs: an analyzer earns trust through false-positive economics, a compiler earns it through a conformance gate that is independent of the compiler. If your tool changes the program rather than judging it → /tensor-compiler-engineering.
• The three pair naturally: a structural verifier that says "this graph is legal and canonical" is a verdict producer (this pack); the artifact it approves is compiled and conformance-checked there.

When to Use

Use this pack when:

• You are building a new analyzer from scratch (a linter, a taint tracker, a contract checker, an entity extractor, a graph-extraction tool, a governance rule engine).
• You inherited an analyzer that works but cannot be extended — rules live as ad-hoc functions, no shared IR, every new check is a special case.
• You need to add typed dataflow (taint, ownership, capability tracking) to a system that currently does pattern matching, and the cost of getting the lattice wrong is years of false positives.
• A team is about to "just write some checks" and you can already see them inventing a fragile shadow-AST that won't survive contact with three-letter dynamic constructs (decorators, metaclasses, eval, dynamic import).
• You need to choose between static enforcement, runtime enforcement, or both for the same property, and the team is leaning whichever way the last bug landed.
• Suppressions in your existing analyzer are growing faster than rules, and nobody can tell you whether the # noqa from 2022 is still load-bearing.

Do not use this pack when:

• You want to run an existing analyzer (ruff, mypy, pylint, semgrep, eslint, clippy) — that is a Python/Rust/JS engineering tooling problem; use /python-engineering, /rust-engineering, or framework-specific guidance.
• You want to consume an analyzer's output to build a system map → /system-archaeologist.
• Your tool rewrites the program rather than judging it — lowering a graph IR, writing torch.fx passes, selecting kernels, fusing operators, or proving a compiled artifact preserves the source's semantics → /tensor-compiler-engineering. Verdict producers live here; executable producers live there.
• You want a turnkey lint config — this pack designs the engine; off-the-shelf analyzers come with their own rule sets.
• You are designing the audit trail of decisions an analyzer makes (who suppressed what, when, why, with what authority) → suppressions are decisions; cross-link to /audit-pipelines. This pack handles the engine; that pack handles the evidence.
• You are doing rule design at the policy or compliance level (NIST control families, SOC 2 criteria) — that is a /security-architect or /sdlc-engineering problem; this pack builds the engine that enforces whatever policy lands.

Start Here

If your input is "we want a static analyzer for X" and you have not run this pack before:

1. Read ast-visitation-patterns.md — choose visitor vs walker vs transformer. The choice constrains everything downstream. Emit 01-visitation-strategy.md.
2. Read taint-lattice-design.md — define the abstract domain. Pick the lattice (the tier set, the join), prove monotonicity and finite height, write the extension rule. Emit 02-abstract-domain-spec.md.
3. Read three-phase-inference.md — order the inference (variable → function → callgraph), specify the worklist, prove termination from the lattice properties of step 2. Emit 03-inference-pipeline-spec.md.
4. Use the Routing section below for plugin architecture, false-positive economics, and the static-vs-runtime boundary.
5. Run the Consistency Gate before declaring 99-analyzer-engineering-specification.md ready.

Steps 1–3 are the spike. The visitation strategy defines what the analyzer sees; the abstract domain defines what it means; the inference order defines how it propagates. If those three artifacts hold together, the rest is fill-in. Most "the analyzer became unmaintainable" stories trace to one of these three: ad-hoc visitation (no shared traversal), a domain that's secretly boolean (just "tainted/clean") even though the code says it's a lattice, or inference that runs in whatever order the developer happened to write functions in.

How to Access Reference Sheets

All reference sheets are in the same directory as this SKILL.md. When you see a link like [taint-lattice-design.md](taint-lattice-design.md), read the file from the same directory.

Pipeline Position

axiom-static-analysis-engineering              axiom-system-archaeologist
  BUILDS analyzers                  ←-cross-ref-→   CONSUMES analyzers
  designs AST visitation,                          runs analyzers, ingests
  abstract domain, inference,                      findings, synthesises a
  rule plugin model, suppression                   system map and dependency
  discipline                                       graph
  ─────────────────────────────────────────────────────────────────────
                            ↓
        A coverage gap the archaeologist finds (an unreachable
        subsystem, an untyped edge, a missing flow) becomes a rule
        request to this pack. This pack ships the rule. The
        archaeologist re-runs and the gap closes.

axiom-audit-pipelines (evidence)               axiom-static-analysis-engineering (engine)
  decisions are evidence;             ←-cross-ref-→   suppressions are decisions;
  canonical bytes, fingerprint                       waiver lifecycle, audit trail
  chains, signed exports                              of who suppressed what
  ─────────────────────────────────────────────────────────────────────
        Suppressions emitted by this pack's analyzer ARE
        audit-grade decisions. Their lifecycle (granted, reviewed,
        expired, re-granted) lives in the audit pack's pipeline.
        Cross-link in 04-rule-plugin-spec.md and 05-fp-economics.md.

ordis-security-architect (policy)              axiom-static-analysis-engineering (enforcement)
  threat models, control families,    ←-cross-ref-→   the engine that enforces
  required invariants                                  whatever invariants land
  ─────────────────────────────────────────────────────────────────────
        Security architect says "untrusted input must not reach
        os.system without sanitisation." This pack builds the
        analyzer that enforces it as a taint rule with a defined
        lattice and a tractable false-positive rate.

Expected Artifact Set

The pack produces a numbered artifact set in an analyzer-engineering/ workspace:

Shipped in v0.2.0:

Commands (v0.2.0): /scaffold-analyzer, /design-tier-model, /design-rule-set. Agents (v0.2.0): rule-designer, false-positive-analyst.

Spec Dependency Graph

The numbered artifacts are not independent — changes propagate. Read this before editing any spec.

01-visitation-strategy.md           (the substrate — what gets walked, in what order)
        │
        ▼
02-abstract-domain-spec.md          (the IR — the lattice the analyzer computes over)
        │
        ▼
03-inference-pipeline-spec.md       (the algorithm — phased fixed-point over the lattice)
        │
        ▼
04-rule-plugin-spec.md              (the extension surface — how rules consume the IR)
        │
        ▼
05-false-positive-economics.md      (the operational reality — suppression lifecycle)
        │
        ▼
06-static-runtime-boundary.md       (the scope statement — what NOT to enforce statically)

Coordinated re-emission rules:

A change not listed above is not exempt; it is evaluated against the consistency gate's affected checks. The default for ambiguity: treat as lattice-breaking unless 02- explicitly tolerates it.

Analyzer Tier

Every analyzer is classified during taint-lattice-design and recorded in 00-scope-and-targets.md. The tier determines which artifacts are required by the consistency gate.

Tier is authoritative. If any sheet's guidance forces an artifact above your declared tier, that artifact becomes required — this is a tier promotion, not a waiver.

Routing

Scenario: "We want a new analyzer for X"

1. ast-visitation-patterns → 01- (pick visitor / walker / transformer based on whether you analyse, query, or rewrite)
2. taint-lattice-design → 02- (define the lattice, prove monotonicity and finite height)
3. three-phase-inference → 03- (order the phases, specify the worklist, prove termination)
4. plugin-architecture-for-analyzer-rules → 04- (rule registry, lifecycle, conflict resolution)
5. false-positive-economics → 05- (suppression lifecycle, waiver discipline, FP-rate budget)
6. static-vs-runtime-tradeoffs → 06- (the boundary statement — what stays runtime, what moves static)
7. Consolidate into 99-analyzer-engineering-specification.md and run the consistency gate.

Scenario: "Our existing analyzer is unmaintainable; rules are ad-hoc, suppressions are out of control"

1. Reverse-engineer the implicit lattice (taint-lattice-design). The analyzer has one whether it acknowledges it or not. Write it down. Most pre-existing analyzers turn out to have a boolean lattice masquerading as a typed system.
2. Reverse-engineer the implicit inference order (three-phase-inference). Where does propagation actually happen? Across functions? Across files? Document the truth, not the marketing.
3. Triage the suppression set (false-positive-economics). Group by rule, by age, by waiver justification. Most "false positives" are rules with the wrong lattice; some are real bugs being silenced.
4. Decide whether to re-engineer in place (steps 4–6 of the previous scenario) or wrap the existing analyzer with a stricter post-filter that's easier to govern.

Scenario: "We need static enforcement of an invariant that is currently runtime-only (or vice versa)"

1. Read static-vs-runtime-tradeoffs first (06-). Most "we should make this static" requests fail under cost analysis: the invariant depends on values, not types, and statics can only see types.
2. If static is genuinely tractable: taint-lattice-design (02-) for the abstract domain that captures the invariant; three-phase-inference (03-) for propagation; plugin-architecture-for-analyzer-rules (04-) for the rule.
3. If dual enforcement is the answer (runtime catches the residual, static catches the bulk): decorator-as-assertion (09-) — record the runtime guard and the static rule under a single agreement contract; both implementations cite it.

Scenario: "Suppressions are growing faster than rules"

1. false-positive-economics (05-) — the lifecycle is broken. Read the suppression lifecycle and audit trail subsections.
2. Cross-link to axiom-audit-pipelines for waiver-as-decision: every # noqa: RULE is a procedural decision and lives in the same evidence regime as governor verdicts.
3. If the rule itself is wrong, taint-lattice-design (02-) — refine the lattice rather than suppress the symptoms.

Specialist Agents

• agent: rule-designer — Given a desired invariant in plain English, drafts a static rule against the existing lattice and inference pipeline; produces RuleMetadata, examples_violation / examples_clean fixtures, and the rule's structural sketch. Surfaces conflicts with existing rules.
• agent: false-positive-analyst — Reviews the suppression set for systemic issues (a single rule with disproportionate suppressions, a waiver pattern that signals lattice mis-design, expiring waivers without review). Classifies suppressions by root cause (lattice imprecision, callgraph over-approximation, stub gap, runtime property masquerading as static, …) and routes findings to the artifact that owns the fix.

Slash Commands

• /scaffold-analyzer — drop in a base AST visitor + rule registry + emission scaffolding (SARIF or native), aligned to the declared analyzer tier; consumes the artifact set this skill produces.
• /design-tier-model — interactive elicitation: what tiers does your trust hierarchy actually need? Output feeds taint-lattice-design.
• /design-rule-set — bootstrap a manifest + initial rule set against an existing analyzer or a fresh scaffold.

Consistency Gate

Run before emitting 99-analyzer-engineering-specification.md. Each check produces a pass/fail line in the gate report. Failures must be addressed or recorded as explicit waivers (with reactivation conditions); silent drops are the failure mode this pack exists to prevent.

A 99-analyzer-engineering-specification.md whose gate report is older than its latest numbered artifact is stale and must be re-gated before downstream citation.

Update Workflows

Bump the 99- semver on every re-emission. Re-gate before downstream citation.

Stop Conditions

Decision Tree

Is the property statically decidable from source structure / types?
├─ No (depends on runtime values) → wrong pack; move to runtime; document in 06-
└─ Yes / partially → Continue

Are you BUILDING the analyzer or RUNNING/CONSUMING one?
├─ Running an existing analyzer (ruff, mypy, semgrep) → /python-engineering, /rust-engineering
├─ Consuming an analyzer's output for a system map → /system-archaeologist
└─ Building / extending → Continue

Pure pattern match (regex over AST, no propagation), or dataflow (taint, ownership, capability)?
├─ Pure pattern → tier XS / S; lattice may be trivial; focus on visitation + rule plugin
└─ Dataflow → tier M+; full spike (visitation + lattice + inference)

Is the analyzer security-bearing (CI-blocking, regulator-visible, control-enforcing)?
├─ No → standard tier (S/M)
└─ Yes → tier L/XL; soundness statement required; suppression lifecycle is non-negotiable

Are suppressions already accumulating in the existing tool?
├─ Yes → start at false-positive-economics (05-); the symptom is downstream of a
        lattice problem (02-) or an inference problem (03-) most of the time
└─ No → standard routing

Integration with Other Skillpacks

System archaeology (axiom-system-archaeologist)

axiom-system-archaeologist consumes analyzers (output → entity catalog,
  dependency graph, security surface map)
→ this pack designs analyzers (input → AST, lattice, inference, rules)
→ a coverage gap the archaeologist finds becomes a rule request to this pack
→ the analyzer extension ships; the archaeologist re-runs; the gap closes

The boundary: archaeologist reads analyzer outputs to synthesise; this pack produces analyzers. They are sibling, not nested. Cross-link in 04-rule-plugin-spec.md (output schema) and in the archaeologist's intake skills (which analyzers are in scope and what they emit).

Audit pipelines (axiom-audit-pipelines)

axiom-audit-pipelines: decisions are evidence; canonical bytes, fingerprint
  chains, signed exports, retention, threat model OF the log
axiom-static-analysis-engineering (this pack): suppressions are decisions

→ a `# noqa: RULE` is a procedural decision (someone decided the rule does
  not apply here, with stated rationale, at a stated time, by a stated
  actor)
→ the suppression lifecycle in 05- is the audit-pipeline lifecycle
  applied to the suppression set
→ cross-link rather than duplicate: 05- cites
  audit-pipelines:retention-expiry-and-rtbf for the waiver-expiry mechanism

Security architecture (ordis-security-architect)

ordis-security-architect produces threat models and required invariants
→ this pack ships the analyzer that enforces them
→ the lattice tiers in 02- correspond to trust boundaries in the
  security architecture (untrusted source → sanitiser → sink)
→ the rule taxonomy in 04- aligns with the control taxonomy
  (CWE alignment, control-family mapping)

The boundary: security architect designs what must be enforced; this pack designs how to enforce it statically (when statically tractable). When it isn't, fall back to runtime — see 06-static-runtime-boundary.md.

SDLC governance (axiom-sdlc-engineering)

this pack produces 99-analyzer-engineering-specification.md
→ sdlc-engineering manages spec lifecycle (rule-set versioning, ADR for
  material lattice changes, retention policy of the analyzer specification
  separate from the suppressions and from the analyzer outputs)

Solution architecture (axiom-solution-architect)

solution-architect's 04-solution-overview.md cites this pack's 99- when
  static analysis is a load-bearing control
solution-architect's adrs/ cite specific choices (lattice shape, inference
  order, plugin loading model)
solution-architect's 17-risk-register.md cites this pack's 99- for
  rule-coverage risk and false-positive-rate risk

Determinism and replay (axiom-determinism-and-replay)

If your analyzer is itself part of a CI pipeline whose results must reproduce across machines (the same code at the same commit must yield the same findings on dev and CI), the analyzer is a deterministic system in the sense of axiom-determinism-and-replay. Most analyzers are; non-determinism in static analysis is usually iteration order over hash maps or wall-clock-keyed caches. Cross-link rather than duplicate.

Quick Reference

The Bottom Line

An analyzer is an engine over a lattice. Pick the visitation, define the abstract domain with monotonicity and finite height, order the inference so it terminates, expose rules through a versioned plugin contract, govern suppressions as auditable decisions, and state the static/runtime boundary in writing. Design the spec before writing the engine; gate the spec for consistency before downstream citation. Without these, you don't have an analyzer — you have a script that occasionally agrees with you.

Static-Analysis-Engineering Specialist Skills Catalog

After routing, load the appropriate specialist sheet for detailed guidance.

Spike (architectural backbone):

1. ast-visitation-patterns.md — Visitor, walker, transformer; lossless vs structural ASTs; parent tracking, source-position preservation, comment handling; choice criteria
2. taint-lattice-design.md — Lattice formalism (partial order, join, monotonicity, finite height); tier model; extension rules; the "boolean lattice masquerading as types" anti-pattern
3. three-phase-inference.md — Variable → function → callgraph; worklist algorithm; termination proof; whole-program vs incremental; cycle handling

Support (operational reality):

4. plugin-architecture-for-analyzer-rules.md — Rule discovery, lifecycle, metadata schema, conflict resolution, deprecation, output schema versioning
5. false-positive-economics.md — Suppression vs refinement; waiver lifecycle; FP-rate budget; cross-link to audit-pipelines for waiver-as-decision
6. static-vs-runtime-tradeoffs.md — What statics can decide; the Rice-theorem ceiling; dual enforcement; cost model

Boundary discipline (added v0.2.0):

7. callgraph-construction.md — Resolution strategies (Rung 0–4: name, CHA, RTA, VTA, k-CFA), virtual dispatch, dynamic imports, monomorphisation, the conservative-top floor and resolution-rate metric
8. cross-module-flow-analysis.md — Boundary semantics, stub library discipline, framework callbacks via synthetic entry points, cross-language FFI, the boundary-statement format
9. decorator-as-assertion.md — Runtime + static agreement contract, descriptor / functools.wraps discipline, the recognition registry, disagreement modes, decorator-aware lattice extension at body entry

Operations (added v0.2.0):

10. manifest-driven-configuration-with-coherence-validation.md — Layered overlays (engine → workspace → project → package → inline), schema and validation passes (syntax, schema, reference, coherence, drift, lifecycle), audit metadata per entry
11. sarif-emission-and-ci-integration.md — SARIF 2.1.0 emission, exit-code semantics (analyzer / config / infra distinguished), suppression round-tripping, fingerprint stability, baseline comparison, consumer matrix
12. scaling-to-large-codebases.md — Three-cache structure (Phase 1 / Phase 2 / Phase 3), cache-key composition that survives lattice / ruleset / stub-library bumps, reverse-edge index, parallelism with determinism, watch mode, partition strategies, incremental-vs-whole-program self-test
13. llm-assisted-rule-explanation.md — The pattern (rule output → structured prompt → LLM → review gate → annotation), not the LLM; boundary statement (model annotates, never decides); prompt-injection threat model; provenance and reproducibility