feat_apply_path_normalizer_declaration: Apply-path-side normalizer declaration (Phase 3 of query-normalization tuning)

[SoundMindsAI]

Why

• Problem: Phase 1 (D-1, option (b)) closes the prod-reproducibility loop with prose: the winning normalizer travels in proposals.config_diff as a scalar query_normalizer value, the PR body's "Operator-side requirement" section names it and embeds a copy-pasteable Python snippet, and the merge contract is "you must replicate this normalizer in your query layer for production parity." That hand-off is adequate when the operator reads PRs end-to-end, owns a Python (or trivially-translatable) query layer, and owns its deployment. It is frictionful when the query layer is owned by a different team without the PR-author's merge rights, when the deployment pipeline expects structured config rather than prose, or when the manual "replicate this" step is forgotten or done wrong — causing the production gain to under-reproduce what the loop measured.
• Outcome: The winning normalizer ships as a structured, language-agnostic manifest in the config-repo PR — not just prose. The operator's CI consumes the manifest directly (parses the YAML, wires it into the query layer's startup config) instead of a human re-implementing a snippet. The merge contract transitions from "copy this Python snippet" to "apply the parameters AND wire the emitted normalizer manifest into your query layer." Production parity becomes a config-consumption step, not a manual re-implementation step.

…(see linked file for the rest)

Status

• Stage: PLAN
• Priority: (see idea file)

Definition of done

Spec defines AC-0: Gating is documented and honored (design-ahead), AC-1: Manifest builder — pure function over the allowlist, AC-2: Manifest ⊆ runtime (I-2), AC-3: Worker emits the manifest file when gate ON, AC-4: Worker does NOT emit the manifest when gate OFF, AC-5: Worker skips manifest when query_normalizer absent, AC-6: Manifest-emit failure → pending, no partial push (I-3), AC-7: PR body references the manifest when gate ON, AC-8: PR body retains Phase 1 wording when gate OFF, AC-9: PR body none-branch (gate ON), AC-10: Proposal-detail manifest preview visible, AC-11: Proposal-detail manifest preview hidden when absent or manual, AC-11b: Manifest preview source has no drift (OQ-1 option 1), AC-12: Single emit site (I-4), AC-13: End-to-end — manifest reaches the PR (real-backend). Each must pass before merge.

Artifacts

• Idea: docs/00_overview/planned_features/02_mvp2/feat_apply_path_normalizer_declaration/idea.md
• Feature spec: docs/00_overview/planned_features/02_mvp2/feat_apply_path_normalizer_declaration/feature_spec.md
• Implementation plan: docs/00_overview/planned_features/02_mvp2/feat_apply_path_normalizer_declaration/implementation_plan.md

How to execute — ⚠️ DESIGN-AHEAD, do NOT /impl-execute yet

This feature is gated (per feature_spec.md §5 + §16) on TWO conditions:

1. feat_query_normalization_tuning: Query normalization as a tunable, opt-in query-time parameter #403 (feat_query_normalization_tuning) Phase 1 has merged — it has NOT (still in Plan stage; no query_normalizer / NormalizerStep symbol exists in backend/app/).
2. Operator-friction evidence that the Phase-1 manual snippet hand-off is actually causing problems.

The feature_spec.md + implementation_plan.md exist as cross-model-reviewed design-ahead artifacts only. Once BOTH gates clear:

/impl-execute docs/00_overview/planned_features/02_mvp2/feat_apply_path_normalizer_declaration/implementation_plan.md --all

Notes

This issue is part of the MVP2 backlog issue-coverage sweep (2026-06-02) — every active MVP2 folder should have a tracking issue so external contributors can discover the work without grep-ing the planned-features tree. If you pick this up, drop a comment so others don't duplicate; if you find the linked idea/spec stale, run /idea-preflight first to refresh it.