docs(cli): cross-reference #1199 in mcp-handler positional-params learning (#1216)

4aba68e686bc124e9a6db06bfe2358ae91b7b227 · 2026-05-12 09:10:33 -0700 · Trevin Chow

* docs(cli): cross-reference #1199 in mcp-handler positional-params learning

A third recurrence in the same template family landed today
(codegen-args-index-vs-positional-ordinal-2026-05-12.md, #1199).
Update the 2026-05-05 learning's Prevention bullet to note the wider
recurrence pattern, add command_promoted.go.tmpl to the list of
emission sites, and cross-link the new doc from Related Issues.

* docs(cli): drop unmerged sibling-doc links, reword "today's" emission sites

Greptile flagged two issues on the #1216 review:
- Both relative-path links to codegen-args-index-vs-positional-ordinal-2026-05-12.md
  point to a file that only exists on fix/path-param-args-index-1199; until that
  branch merges, the links 404 on main. Drop the relative-path references — the
  #1199 issue link survives in both places and the new sibling doc, once landed,
  already cross-links back here, so the trail stays walkable.
- "Today's emission sites" implied 2026-05-05-era parity for a list that now
  includes command_promoted.go.tmpl (added by #1199 a week later). Reword to
  "Known emission sites (as of #1199)" so future readers don't infer a
  timeline they weren't getting.

Files touched

M docs/solutions/logic-errors/mcp-handler-conflates-path-and-query-positional-params-2026-05-05.md

Diff

commit 4aba68e686bc124e9a6db06bfe2358ae91b7b227
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Tue May 12 09:10:33 2026 -0700

    docs(cli): cross-reference #1199 in mcp-handler positional-params learning (#1216)
    
    * docs(cli): cross-reference #1199 in mcp-handler positional-params learning
    
    A third recurrence in the same template family landed today
    (codegen-args-index-vs-positional-ordinal-2026-05-12.md, #1199).
    Update the 2026-05-05 learning's Prevention bullet to note the wider
    recurrence pattern, add command_promoted.go.tmpl to the list of
    emission sites, and cross-link the new doc from Related Issues.
    
    * docs(cli): drop unmerged sibling-doc links, reword "today's" emission sites
    
    Greptile flagged two issues on the #1216 review:
    - Both relative-path links to codegen-args-index-vs-positional-ordinal-2026-05-12.md
      point to a file that only exists on fix/path-param-args-index-1199; until that
      branch merges, the links 404 on main. Drop the relative-path references — the
      #1199 issue link survives in both places and the new sibling doc, once landed,
      already cross-links back here, so the trail stays walkable.
    - "Today's emission sites" implied 2026-05-05-era parity for a list that now
      includes command_promoted.go.tmpl (added by #1199 a week later). Reword to
      "Known emission sites (as of #1199)" so future readers don't infer a
      timeline they weren't getting.
---
 ...cp-handler-conflates-path-and-query-positional-params-2026-05-05.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/solutions/logic-errors/mcp-handler-conflates-path-and-query-positional-params-2026-05-05.md b/docs/solutions/logic-errors/mcp-handler-conflates-path-and-query-positional-params-2026-05-05.md
index 46f6e0b3..5c0c4557 100644
--- a/docs/solutions/logic-errors/mcp-handler-conflates-path-and-query-positional-params-2026-05-05.md
+++ b/docs/solutions/logic-errors/mcp-handler-conflates-path-and-query-positional-params-2026-05-05.md
@@ -119,7 +119,7 @@ The fix is local to the template body and doesn't change the call-site contract
 
 ## Prevention
 
-- **This is a recurrence.** [#171 WU-1](https://github.com/mvanhorn/cli-printing-press/issues/171) fixed the identical bug in the sibling template `command_endpoint.go.tmpl` (CLI surface) earlier. The fix did not propagate to `mcp_tools.go.tmpl`. Treat any future generator template that consumes `positionalParams` as a candidate for the same guard. Today's emission sites: `command_endpoint.go.tmpl`, `mcp_tools.go.tmpl`. Add the check at any new site that joins them.
+- **This is a recurring bug family.** [#171 WU-1](https://github.com/mvanhorn/cli-printing-press/issues/171) fixed the identical bug in the sibling template `command_endpoint.go.tmpl` (CLI surface) earlier; the fix did not propagate to `mcp_tools.go.tmpl` (this learning, #578). [#1199](https://github.com/mvanhorn/cli-printing-press/issues/1199) is a third recurrence on a different axis — `args[]` indexing rather than path-vs-query disambiguation — that hit `command_endpoint.go.tmpl` and `command_promoted.go.tmpl`. Treat any future generator template that consumes `positionalParams`, or computes an index/category from `Endpoint.Params`'s ordering, as a candidate for the same guard. Known emission sites (as of #1199): `command_endpoint.go.tmpl`, `command_promoted.go.tmpl`, `mcp_tools.go.tmpl`. Add the check at any new site that joins them.
 - When a generator-emitted handler branches on a parameter list, verify the list's runtime semantics match the handler's assumed category before writing the branch. If the call site composes the list from multiple `Param.*` predicates (here: `Param.Positional || Param.PathParam`), treat each predicate as a distinct category in the handler too — don't collapse them by reusing the slice as a single set.
 - Prefer the most authoritative runtime artifact (here: `pathTemplate`) as the disambiguator instead of a name list assembled at codegen time. Name lists drift from intent; the template literal does not.
 - Whenever a defect in `internal/generator/templates/mcp_tools.go.tmpl` only manifests on the MCP surface, treat it as a class of bug, not a one-off. The CLI surface flattens many shapes before they reach shared code, so MCP-only regressions are easy to ship. Add the regression test at the generator level (assert on rendered template output + `runGoCommand("build")`) rather than at the printed-CLI level.
@@ -132,6 +132,7 @@ The fix is local to the template body and doesn't change the call-site contract
 - [#578](https://github.com/mvanhorn/cli-printing-press/issues/578) — original issue (this fix)
 - [#582](https://github.com/mvanhorn/cli-printing-press/pull/582) — PR that landed the fix
 - [#171 WU-1](https://github.com/mvanhorn/cli-printing-press/issues/171) — same bug, sibling template (`command_endpoint.go.tmpl`), fixed earlier; the fix did not propagate
+- [#1199](https://github.com/mvanhorn/cli-printing-press/issues/1199) — third recurrence in the same template family (args[] index drift in `command_endpoint.go.tmpl` and `command_promoted.go.tmpl`)
 - [printing-press-library#232](https://github.com/mvanhorn/printing-press-library/issues/232) — Movie Goat backport (merged)
 - [printing-press-library#233](https://github.com/mvanhorn/printing-press-library/issues/233) — Shopify, Linear, Archive.is, Weather Goat, Cal.com backports (merged)
 - [#437](https://github.com/mvanhorn/cli-printing-press/issues/437) — adjacent template hygiene (URL building correctness in `client.go.tmpl`)

← 7365fcc3 fix(cli): resolve validation binary path with platform.Execu · back to Cli Printing Press · fix(cli): emit stderr truncation warning on single-page list 6cda2606 →