Reconcile proposed zsh-lint architecture ADR 0011 with the shipped analyzer

[ss-o]

Objective

Reconcile ADR 0011 with the semantic analyzer shipped on z-shell/zsh-lint main, then record an explicit maintainer decision to revise it in place or supersede it.

Audit pin — 2026-07-18

• zsh-lint main: e714dc3e1b4af8d938eb70f7c5655bf17636068d (promotion PR #84).
• PR build(deps): bump github/codeql-action from 2.2.1 to 2.2.2 #84 and current main have the same tree.
• Trunk, Go CI, Zsh Syntax Check, and Docs Generate Check passed on the promoted change.

Shipped architectural boundary

The durable design is a conditional two-pass semantic core inside a three-phase diagnostic pipeline:

1. Scope indexing runs only when a rule implements ScopeAwareRule and returns NeedsScope() == true.
2. The analyzer walks nodes and evaluates registered rules.
3. Suppression directives are collected/applied, meta/* diagnostics are preserved or added, and diagnostics are sorted once.

Additional verified facts:

• No production rule currently requests scope; the opt-in exists in the engine and tests.
• Rule requires ID() diag.RuleID, Name() string, and Analyze(ctx *Context, node syntax.Node).
• Context.Report accepts positions, rule ID, severity, and message; there is no AnalyzerContext.Report(diagnostic) API.
• The scope index is intentionally approximate rather than flow-sensitive local/global resolution.
• Stable IDs, deterministic ordering, versioned JSON, suppression behavior, parser-gap handling, and rule evidence have their own product contracts and should be linked rather than copied into the ADR.

Claims requiring reconciliation

• “is transitioning” is stale: the standalone Go analyzer is shipped.
• Unconditional two-pass wording is incorrect.
• “use before declaration with high accuracy” describes no shipped rule and is unsupported.
• “walking twice is negligible” is unmeasured; syntax-only and scope-aware runs do not have the same walk count.
• Adding a rule requires more than interface registration: stable ID, registry entry, tests, documentation, and rule-policy evidence are part of the shipping contract.
• The single-pass alternative remains useful rationale but must not imply an existing undefined-function rule.

Draft implementation and review — 2026-07-18

• Draft PR #456 contains the ADR-only reconciliation at 71286af3.
• Focused Trunk markdownlint and git diff --check pass.
• All referenced zsh-lint source and contract paths were resolved against the audited commit.
• Independent review approved both specification compliance and document quality with no remaining findings.
• Live CodeQL Advanced run 29637275127 succeeded on exact head 71286af3.
• The ADR remains PROPOSED; no analyzer behavior changed.

Maintainer decision requested

Recommended outcome: revise ADR 0011 in place because the separation of optional indexing from rule evaluation remains recognizable.

Please decide:

1. Retain optional scope indexing as an intended extension point even though no production rule consumes it yet.
2. Keep the current ADR title or rename the decision around the conditional pipeline.
3. Accept it with a named decider/date, keep it proposed with explicit objections, amend it, supersede it, or reject it.

Checklist

• Compare ADR 0011 with the promoted analyzer, scope, suppression, diagnostics, and contract documentation.
• Identify the exact phase, interface, scope-model, performance, and precision drift.
• Prepare the ADR-only patch while retaining PROPOSED.
• Link stable contracts instead of copying transient schemas or rule inventory.
• Verify Markdown/style checks and source references.
• Complete independent specification and quality review.
• Record the maintainer decision and synchronize it with Linear.

Boundaries

This is architecture documentation and decision review. It must not change zsh-lint behavior merely to make the implementation resemble the old proposal. Avoid transient PR numbers, commit SHAs, current rule counts, and workflow inventories in the durable ADR.

Triage

Suggested item type: Documentation / architecture
Suggested priority: Medium
Suggested effort: Low
Suggested status: In review

Linear mirror: ZSH-23

[ss-o]

Maintainer decision packet — 2026-07-19

State pin:

• Draft PR docs(adr): reconcile zsh-lint analyzer architecture #456 is open, clean/mergeable, and changes only ADR 0011 at head 71286af374206649fc9f4326c4aa83b018a9fb53.
• The exact-head audit found successful CodeQL/Lychee checks and no requested reviewers, reviews, comments, or review threads.
• The reconciled text matches the analyzer shipped on zsh-lint main; it remains PROPOSED and changes no analyzer behavior.

Decision A — optional scope indexing

• 11A — Retain the opt-in extension point (recommended). This matches the shipped ScopeAwareRule.NeedsScope() boundary and tests. No production rule needs scope today, but syntax-only rules remain independent of indexing and future complete-file rules have an explicit boundary.
• 11B — Remove it. This would simplify currently unused production behavior, but it requires a separate zsh-lint design/code change and discards a tested extension point without evidence of harm.
• 11C — Make indexing unconditional. This contradicts the shipped conditional pipeline and makes syntax-only rules pay for unused state.

Decision B — ADR title

• T1 — Rename the heading to “zsh-lint Conditional Semantic Analysis Pipeline” (recommended). It states the actual decision while the filename may remain stable to avoid link churn.
• T2 — Keep “zsh-lint Semantic Analyzer Architecture.” Less churn, but broader than the decision actually recorded.

Decision C — disposition

• D1 — Revise in place and accept (recommended). The original proposal was never accepted, and the recognizable architectural boundary remains; superseding it would add history without clarifying the decision.
• D2 — Keep proposed with explicit objections. Record the unresolved objection in this issue and ADR before leaving it proposed.
• D3 — Supersede or reject. Use only if the maintainer does not intend to preserve conditional scope indexing or this diagnostic pipeline.

Recommended coherent selection: 11A / T1 / D1.

Copy-ready acceptance record:

Title: zsh-lint Conditional Semantic Analysis Pipeline
Status: ACCEPTED
Date: <YYYY-MM-DD decision date>
Deciders: ss-o
Decision: Retain optional ScopeAwareRule-based indexing inside the documented
three-phase diagnostic pipeline; scope remains approximate and opt-in.
Authorization: update PR #456, run the documented verification again, mark it
ready, and merge only if the exact accepted head remains green.

After explicit approval, it becomes safe to update only the ADR heading/metadata and remove the “proposal” review paragraph, re-run formatting/link/diff checks, obtain final review, mark PR #456 ready, merge it, close #455, and move ZSH-23 to Done. It does not authorize a zsh-lint behavior change.

Reply with 11A / T1 / D1, approve patch and merge, or provide amended codes/text.