docs(design): conduit generate — AI-assisted pipeline generation

[devarismeroxa]

Summary

Design doc for conduit generate (v0.19 roadmap item, Agent-native section) — a natural-language-to-pipeline-config command, gated by the existing validate engine plus a new deterministic semantic-intent checker, with deployment only ever reachable through a TTY-confirmed hand-off to the existing deploy/apply machinery.

Status: APPROVE-WITH-CHANGES. This revision applies an independent review pass focused on hardening the prompt-injection trust boundary before any code is written. No feature code in this PR — doc only, per CLAUDE.md's design-doc-before-code rule.

Findings applied

• HIGH — confirm-precedent grounding. Corrected the claim "no interactive confirm exists in the CLI today": pipelines deploy --apply's confirm() (cmd/conduit/root/pipelines/deploy.go:198-212) already reads a line from cmd.InOrStdin() unconditionally, with no isatty gate, so a piped y is read as affirmative even non-interactively. The doc now states generate MUST isatty-gate both stdin and stdout before reading any confirmation, and MUST NOT reuse that unconditional-read shape — named explicitly in Context, Decision §4, the Upgrade/rollback ADR note, and the Testing section's load-bearing security-test bullet.
• HIGH — untrusted model text in the human decision. The [y/N] decision is now explicitly anchored on the YAML diff + deterministic semantic-check results (trusted); rationale/assumptions[] are called out as unverified model output, visually marked, never the primary basis for a yes/no. Also corrected §4's "no code-execution surface, therefore harmless" framing — a deployed pipeline is a data-movement primitive (source → external sink = exfiltration channel); the bound is now stated as "the deployed effect is limited to what deploy/apply would let any config do," not "schema-shaped therefore safe." Failure-mode npm: bump sinon from 9.2.4 to 12.0.1 in /ui #4 (prompt injection) updated to match.
• MEDIUM — --out path traversal. Specified that the model-controlled inferred filename is sanitized to a bare basename within cwd (path separators and .. stripped/rejected); --out never escapes the working directory without an explicit user-supplied path. Independent of the TTY/confirm boundary since it needs no confirmation at all. Added a corresponding Testing bullet.
• MEDIUM — MCP cost amplification. Added Failure Mode Reorder processors #9: the always-on read-only MCP generate tool lets any connected agent trigger outbound LLM calls on the operator's key/cost with agent-controlled prompts; --max-retries bounds one call, not calls-per-session. Named mitigation lever: a per-session call budget, or documented reliance on provider-side rate/spend caps until one exists.
• MEDIUM — ambiguous_prompt pre-call refusal too aggressive. Made the pre-call refusal conservative — refuses only clearly-empty/self-contradictory prompts; borderline prompts now pass through to the provider and are judged post-hoc by the semantic checker. ambiguous_prompt is now documented as a post-hoc code as much as a pre-filter.
• LOW — semantic score oversell. Clarified the ≥70% semantic-intent floor answers coarse mismatch (wrong connector/direction/missing capability) only, not fine predicate correctness (wrong filter condition/table) — reworded so 70% isn't read as "70% are correct."
• LOW — per-call timeout. Added a default per-attempt provider context deadline (overridable), so a hung provider fails to provider_error instead of wedging, plus a one-line note that grounding-prompt size × retries is the token-cost lever.
• LOW — fuzzymatch spec. Concretely specified the similarity floor (edit distance ≤2 OR ≤30% of len(want)), case-insensitivity, and that plain Levenshtein (not Damerau) is adequate for v1.
• Upgrade/rollback ADR note now explicitly requires the future ADR to capture the isatty-gate/no---yes reasoning and the --out sanitization reasoning, so both survive without archaeology.
• Eval harness clarification. Replay-mode PR CI is now explicitly documented as a Conduit-code regression gate, not a provider-quality signal — a provider regression leaves old passing transcripts in place, so PR CI stays green regardless.

Test plan

• npx markdownlint-cli2 --fix — clean, 0 errors
• Human (DeVaris) review of the hardened trust-boundary language before this is treated as a settled design

🤖 Generated with Claude Code