---
category: index
bucket: patterns
generated: true
---

# Patterns Index

Generated by `goat-flow index`; do not edit by hand. Each row below maps one pattern entry to its source file with a grep-friendly `(search: "...")` anchor. Re-run `goat-flow index` after adding, editing, renaming, or resolving entries - `goat-flow stats --check` fails while this file is stale. Live entry counts and freshness come from `goat-flow stats`.

- [UNSET sentinel + recursive merge for layered CLI overlays](architecture.md) (search: "## Pattern: UNSET sentinel + recursive merge for layered CLI overlays") - A CLI exposes options that override values in N configuration layers (default config file, project config file, user config file, command-line flags).
- [Hot-import deferral for slow CLI dependencies](architecture.md) (search: "## Pattern: Hot-import deferral for slow CLI dependencies") - A CLI invocation pays for every top-level `import`/`require` of every module it loads, even when the user only runs `--help` or a fast subcommand.
- [Use POSIX-shape paths for every user-visible string](architecture.md) (search: "## Pattern: Use POSIX-shape paths for every user-visible string") - Anywhere a `path.*` result is embedded in CLI output, prompts, audit findings, JSON payloads, dashboard rendering, log messages, or shell snippets the user/agent will execute.
- [Model cross-platform PTY launches as pure spawn specs](architecture.md) (search: "## Pattern: Model cross-platform PTY launches as pure spawn specs") - Terminal or runner integrations that must work on native Windows and POSIX shells.
- [Summary surfaces should use cheap evidence and reserve full proofs for drill-ins](architecture.md) (search: "## Pattern: Summary surfaces should use cheap evidence and reserve full proofs for drill-ins") - Dashboard home cards, aggregate setup summaries, or any overview route that only needs to answer "is this mechanism installed?" rather than "does the full runtime proof pass right now?" Approach:…
- [Split guardrails by operational decision](architecture.md) (search: "## Pattern: Split guardrails by operational decision") - A safety hook grows multiple policy categories with different risk profiles, self-test corpora, default states, or dashboard toggle needs.
- [Asymmetric trust - set state from output, clear state from input](architecture.md) (search: "## Pattern: Asymmetric trust - set state from output, clear state from input") - Any state machine that classifies streaming PTY / WebSocket / SSE output to track "is the producer blocked on user input." The producer is a third-party TUI (coding agent, language REPL, build tool)…
- [Pin AWAY from known-bad versions via `!=`, not only `>=`](dependencies.md) (search: "## Pattern: Pin AWAY from known-bad versions via `!=`, not only `>=`") - A dependency you ship in your own `package.json` / `pyproject.toml` constraint is disclosed as compromised (supply-chain attack, malicious version, broken release).
- [Multi-agent critique - how to run it effectively](multi-agent.md) (search: "## Pattern: Multi-agent critique - how to run it effectively") - Commissioning multiple independent agent reviews of a framework, architecture, or release candidate.
- [Convert self-declared critique gates into executable checks](multi-agent.md) (search: "## Pattern: Convert self-declared critique gates into executable checks") - A multi-agent critique skill asks sub-agents to declare dimensions, isolation, lens coverage, or severity calibration, then the orchestrator uses those declarations to make decisions.
- [Canary-first contract changes (one consumer before all consumers)](refactoring.md) (search: "## Pattern: Canary-first contract changes (one consumer before all consumers)") - Changing a contract that has N consumers (every env class, every audit check, every renderer, every agent config) — the change must propagate to every consumer to land.
- [Verify structural renames with a repo-wide grep](refactoring.md) (search: "## Pattern: Verify structural renames with a repo-wide grep") - Renaming setup files, moving shared references, or changing canonical doc paths.
- [Skill consolidation requires a full grep after every merge](refactoring.md) (search: "## Pattern: Skill consolidation requires a full grep after every merge") - Renaming, merging, or deleting skills.
- [Put prompt side effects on the CLI side of the boundary](refactoring.md) (search: "## Pattern: Put prompt side effects on the CLI side of the boundary") - A prompt contract forbids tracked-file writes or unrestricted I/O, but a new feature needs persistence, capture, or report history.
- [Sandwich-layer refactor for behavior-preserving migration of load-bearing seams](refactoring.md) (search: "## Pattern: Sandwich-layer refactor for behavior-preserving migration of load-bearing seams") - Changing a load-bearing boundary type with many call sites on both sides — a request/response envelope, a check-result schema, a manifest shape, an evidence envelope.
- [Cross-runner quality-report triage by convergence](verification.md) (search: "## Pattern: Cross-runner quality-report triage by convergence") - `goat-flow quality` runs produce a JSON report per runner.
- [Auto-detect required runtime in CI, skip cleanly when absent](verification.md) (search: "## Pattern: Auto-detect required runtime in CI, skip cleanly when absent") - Tests that depend on an external runtime (container engine, language runtime, native binary) may be valuable in some CI environments but unrunnable in others.
- [Bounded wait loops in tests, never bare `while not condition`](verification.md) (search: "## Pattern: Bounded wait loops in tests, never bare `while not condition`") - Integration tests that wait for an external state change (server ready, session attached, event delivered, file appeared) can hang indefinitely if the state never arrives.
- [Verification scope must match change scope](verification.md) (search: "## Pattern: Verification scope must match change scope") - Any change that touches more than just code.
- [Complexity refactors need file-level lint before closeout](verification.md) (search: "## Pattern: Complexity refactors need file-level lint before closeout") - Reducing complexity in a specific function.
- [Refactors need typecheck before preflight](verification.md) (search: "## Pattern: Refactors need typecheck before preflight") - After a large extraction or restructuring pass.
- [Non-gating audit gaps belong in explicit limits](verification.md) (search: "## Pattern: Non-gating audit gaps belong in explicit limits") - A deterministic audit check passes by design, but review evidence shows a reader could over-interpret the PASS as complete assurance.
- [Source-grep guardrail for banned API surfaces](verification.md) (search: "## Pattern: Source-grep guardrail for banned API surfaces") - A particular API or coding pattern has been identified as dangerous in some scope (`sql.raw` with string concat, `eval()`, `Math.random()` for security-bearing IDs, `console.log` in MCP server code,…
- [Verification needs a real context boundary](verification.md) (search: "## Pattern: Verification needs a real context boundary") - The same agent writes a change and then proposes to "independently verify" it inside the same invocation.
- [Phase-boundary PR template for oversize work](workflow.md) (search: "## Pattern: Phase-boundary PR template for oversize work") - A change exceeds practical PR review size (~3000 lines or 20+ files, or GitHub's "exceeds 20,000 lines" Copilot cap) or naturally divides into phases (foundation -> hardening -> automation -> polish).
- [Deny-rule grammar matrix before mirror fanout](workflow.md) (search: "## Pattern: Deny-rule grammar matrix before mirror fanout") - Adding or changing a deny hook rule for an external CLI with subcommands, inherited flags, or pipeline use.
- [Dry-run readiness belongs beside the command](workflow.md) (search: "## Pattern: Dry-run readiness belongs beside the command") - A command can write files, launch terminals, mutate harness config, or ask an agent to act.
- [Skill-playbook structural template](workflow.md) (search: "## Pattern: Skill-playbook structural template") - Authoring a new playbook for `workflow/skills/playbooks/` (browser-use, page-capture, observability, code-comments, changelog, release-notes, skill-quality-testing are the established examples).
- [Gruff docs cleanup is a tight analyzer loop](workflow.md) (search: "## Pattern: Gruff docs cleanup is a tight analyzer loop") - Fixing `gruff-ts` documentation findings by adding maintainer comments, especially `docs.missing-*`, `docs.magic-threshold-without-rationale`, `docs.missing-error-behavior-doc`, or…
