📖 [Docs]: Reusable pipeline prefetch specification

[Marius Storhaug (MariusStorhaug)]

Pipeline prefetch has a reusable specification and design, with GitHub as the first adoption profile. These documents describe intended behavior for discussion, not a released feature. This is documentation only: no runtime behavior changes.

The contract specifies automatic prefetch for eligible paginated result producers with an explicit opt-out, while preserving ordered streaming output, request policies, bounded lookahead, cancellation, and context isolation. It does not make every pipeline-input command concurrent or change mutation, consumer, or raw GraphQL query behavior.

---

Technical details

• Adds the supplied index.md, spec.md, design.md, and implementation.md together under docs/pipeline-prefetch/, plus README navigation. Document bodies are preserved; frontmatter uses ms.title to fit the existing Markdown rules and framework convention.
• The GitHub profile targets -NoPrefetch and one future page by default, counting queued, producer-held, and in-flight pages together. This is distinct from the prototype's node-count QueueCapacity. Adoption covers all eligible REST and GraphQL list paths, not only repository connections.
• The design requires a module-private in-process producer, foreground emitter, provider pagination adapters, and the established shared single-request transport rather than a worker that bypasses retry, authentication, or response policies.
• This checkout has no authored documentation tree. The README links to the canonical repository page because the pinned site assembler copies README unchanged but does not publish standalone repository docs. That main URL becomes available when this PR is merged; links between the four pages are relative. No site configuration, build tooling, or runtime files change.

Implementation scope: only the documentation and navigation are delivered. This branch is based independently on main, not stacked on #645. Related-work review is limited to #644 and #645; neither is completed or closed by this change.

Validation: the existing Markdown linter passes for all five changed files, and the existing codespell configuration passes for the four new documents. The nine relative document links, README target, requirement/scenario completeness, immutable source references, and staged diff were inspected. No module tests or full module/site build were run for this documentation-only change.

Changed surface	Standards checked	Framework docs checked	Result
docs/pipeline-prefetch/*.md	MSX documentation model and artifact templates; Natural Language; repository Markdown rules	Module layout and pinned documentation assembly	Aligned
README.md	MSX documentation navigation; Natural Language; repository Markdown rules	Pinned README/site assembly	Aligned

This PR remains draft for discussion. CI, automated PR review, and other ready-for-review gates are not represented as complete. Auto-merge is not enabled.

Relevant issues (or links)

Related work

• References Investigate paginated prefetch for repository pipelines and common API path support #644 for the paginated-prefetch motivation and intended shared API direction.
• References Prototype GraphQL connection prefetch #645 for the existing repository-connection prototype; this PR neither modifies nor depends on it.

[github-actions]

Super-linter summary

Language	Validation result
CHECKOV	Pass ✅
GITHUB_ACTIONS	Pass ✅
GITLEAKS	Pass ✅
GIT_MERGE_CONFLICT_MARKERS	Pass ✅
MARKDOWN	Pass ✅
NATURAL_LANGUAGE	Pass ✅
PRE_COMMIT	Pass ✅
SPELL_CODESPELL	Pass ✅
TRIVY	Pass ✅
YAML	Pass ✅

All files and directories linted successfully

For more information, see the GitHub Actions workflow run

Powered by Super-linter