@mmerterden/multi-agent-pipeline 10.12.0 → 11.1.0

package/CHANGELOG.md

@@ -14,6 +14,64 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [11.1.0] - 2026-07-07
+
+Harness-hardening pass: four techniques adapted from studying cross-harness agent
+operating systems, all additive and opt-in.
+
+- **Guard hooks (`agent-guard.sh`)** — a new PreToolUse Bash gate that turns two
+  prompt-level rules into deterministic, OS-enforced blocks: AI/assistant
+  attribution in a commit message, and force-push to a protected branch
+  (main/master/develop). Fail-open on any internal error, never executes the
+  inspected command (decision core is `agent-guard.py`, shlex-tokenized only),
+  no network, no secret output. Wired into `install/templates/claude-hooks.json`
+  alongside the existing secret scan; `multi-agent:setup` offers to merge it.
+  Backed by `smoke-agent-guard.sh` (19 behavioral cases incl. injection safety).
+- **Config-hygiene gate (`scan-agent-config.sh`)** — a dependency-free, read-only
+  audit of the shipped config surface (hook templates, preferences template,
+  agent defs, MCP helper scripts) for hardcoded secrets, permission-bypass flags,
+  eval-bearing hook commands, blanket `Bash(*)` allows, and pipe-to-shell /
+  unpinned-npx install patterns. Runs in the release VERIFY step; blocks on any
+  HIGH finding. Backed by `smoke-config-hygiene.sh` (real surface clean +
+  planted-bad detection).
+- **Autopilot circuit-breaker** — `refs/features/autopilot-circuit-breaker.md`
+  defines the sanctioned autopilot pause: halt and hand back to the user on a
+  no-progress stall, an identical repeated failure, a rework storm, cost drift
+  past the `costBudget` ceiling, or a merge/rebase conflict. Continuing
+  unattended off the happy path is the less safe choice.
+- **Three technique skills** added to `ai-common-engineering-toolkit`
+  (v0.1.1): `council` (multi-voice adversarial decision), `search-first`
+  (research-before-coding with an adopt/extend/compose/build matrix), and
+  `agent-introspection-debugging` (capture -> diagnose -> contained-recovery ->
+  report, with an honesty guard against fake auto-heal claims).
+
+## [11.0.0] - 2026-07-07
+
+Breaking: the two issue creators `generate-task` and `generate-bug` are merged
+into a single `generate` command. The command surface shrinks from 37 to 36
+commands, so this is a major bump per the versioning policy (a renamed/removed
+command is a breaking surface change).
+
+- **New `/multi-agent:generate`** asks the issue type (Task / Bug / Story) at the
+  start of every run, then mines the project's recent same-type issues for
+  conventions and drafts the issue.
+- **Standard template baseline with auto-sizing.** Each type has a fixed section
+  skeleton (Task/Story: Detailed Description, Scope, Acceptance Criteria, Test
+  Scenarios; Bug: Detailed Description, Steps to Reproduce, Expected/Actual
+  Result, Environment). Conditional sections (Design Reference, API Contract /
+  Swagger, Screenshots, Notes) render only when their trigger is present  -  no
+  empty placeholder headings, nothing invented.
+- **Test Scenarios pulled from Jira convention.** Detects linked Xray/Zephyr test
+  issues or a dominant test-scenario heading style and reuses it; falls back to an
+  AC-derived skeleton the user edits.
+- **Swagger / API Contract section.** When a Swagger/OpenAPI URL or contract is
+  given, fetches only the referenced endpoints (method + path + key fields) and
+  links the spec. No full-spec crawl; failures degrade to link-only.
+- **Removed** `generate-task` and `generate-bug` on both CLIs (Claude Code +
+  Copilot) and the plugin skill set. The shared `refs/generate-issue.md` flow is
+  now 12 steps with a dedicated type-selection step; the hard approval gate is
+  unchanged.
+
 ## [10.12.0] - 2026-07-06
 
 Two trust upgrades: every external channel post now shows a plan-mode-style

package/install/templates/claude-hooks.json

@@ -1,5 +1,5 @@
 {
-  "_readme": "Recommended Claude Code hooks for multi-agent-pipeline. Merge the `hooks` object into your ~/.claude/settings.json to make the secret scan a HARD pre-commit gate (exit 2 blocks the commit) rather than an advisory step. This is the one gate that is naturally a PreToolUse hook: it scans the staged diff with no extra arguments. The other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with run-specific arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable. multi-agent:setup offers to merge this block.",
+  "_readme": "Recommended Claude Code hooks for multi-agent-pipeline. Merge the `hooks` object into your ~/.claude/settings.json to make these deterministic, OS-enforced PreToolUse gates real (exit 2 blocks the tool call) rather than prompt-level hopes. Two gates ship here: (1) a staged-diff secret scan on git commit (pre-commit-check.sh); (2) an agent-guard on git commit + git push (agent-guard.sh) that blocks AI/assistant attribution in commit messages and force-push to a protected branch (main/master/develop). Both scripts are self-contained, fail-open on internal error, never execute the inspected command, and need no run-specific arguments, which is why they are naturally PreToolUse hooks. The other deterministic gates (evidence, consensus, intent, learnings) take run-specific arguments and are phase-enforced by the pipeline instead. multi-agent:setup offers to merge this block.",
   "hooks": {
     "PreToolUse": [
       {
@@ -10,6 +10,23 @@
             "command": "bash $HOME/.claude/scripts/pre-commit-check.sh",
             "timeout": 15,
             "statusMessage": "Scanning staged changes for secrets..."
+          },
+          {
+            "type": "command",
+            "command": "bash $HOME/.claude/scripts/agent-guard.sh",
+            "timeout": 10,
+            "statusMessage": "Checking commit for attribution..."
+          }
+        ]
+      },
+      {
+        "matcher": "Bash(git push:*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash $HOME/.claude/scripts/agent-guard.sh",
+            "timeout": 10,
+            "statusMessage": "Checking push safety..."
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "10.12.0",
+  "version": "11.1.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code and Copilot CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/commands/multi-agent/generate.md

@@ -0,0 +1,34 @@
+---
+description: "Create a standards-compliant Jira issue (Task / Bug / Story): asks the type, mines project conventions, drafts from a standard template with auto-sizing sections, full preview + explicit approval before create."
+argument-hint: "[\"<free-text description>\"] [figma-url] [swagger-url]  -  all optional, asked interactively when missing"
+---
+
+# multi-agent generate  -  Standards-Compliant Jira Issue Creator
+
+**Input**: $ARGUMENTS
+
+Creates exactly one Jira issue, and only after explicit approval. The issue type (Task / Bug / Story) is asked at the start of every run. No branches, no commits, no worktrees, no pipeline chaining. The draft learns the target project's conventions from its recent same-type issues (summary format, labels, components, priority norms, test-scenario style) and offers active-sprint placement when a sprint is running.
+
+> **Language**: instruction prose here is English. AskUserQuestion `question`/`description` and the issue content (summary + description) follow `prefs.global.outputLanguage`  -  an intentional exception to the "external payloads stay English" default, because the issue is authored for the user's team. `label`/`header` stay English.
+
+## Issue types
+
+Type is chosen at step [3/11] via AskUserQuestion (never inferred silently). Each type has a standard template baseline; sections auto-size (see `refs/generate-issue.md` for the full A/C matrix and inclusion rules).
+
+| Type | Always-present sections | Conditional sections (included only when their trigger is present) |
+|---|---|---|
+| `Task` | Detailed Description, Scope, Acceptance Criteria, Test Scenarios | API Contract / Swagger, Design Reference, Screenshots, Notes |
+| `Bug` | Detailed Description, Steps to Reproduce, Expected Result, Actual Result, Environment | Screenshots / Logs, Regression / Test Scenario, API Contract, Design Reference, Notes |
+| `Story` | User Story, Detailed Description, Scope, Acceptance Criteria, Test Scenarios | API Contract / Swagger, Design Reference, Screenshots, Dependencies / Notes |
+
+## Flow
+
+Read `$HOME/.claude/commands/multi-agent/refs/generate-issue.md` and execute the 11-step shared flow. Non-negotiables restated:
+
+- Ask the user (AskUserQuestion) for the issue type first, then about every genuinely unknown field  -  component, epic, priority, labels, assignee, sprint vs backlog, required custom fields.
+- A conditional section renders only when its trigger is present (Figma URL, pasted screenshot/log, Swagger URL/contract, real Notes content). No empty placeholder headings; content the user did not supply and mining could not derive is never invented.
+- Step [8/11] full preview + approval gate always runs. `Approve` / `Edit` (loop) / `Cancel`. No bypass exists.
+
+## Error paths
+
+See `refs/generate-issue.md` Error paths. No command-specific additions.

package/pipeline/commands/multi-agent/help.md

@@ -111,8 +111,7 @@ Post-Hoc & Side-Channel:
   /multi-agent:analysis ["analysis-name"]  Feature-spec analysis (Figma + Swagger + Confluence + repos) → per-platform v3 doc (23-section Full / 7-section Lite)
   /multi-agent:analysis-resolve [doc]      Resolve Section 20 open questions of an analysis doc, one at a time with source-labeled candidates
   /multi-agent:build-optimize iOS-only Xcode build perf wrapper → benchmark + analyze + recommend-first .build-benchmark/optimization-plan.md
-  /multi-agent:generate-task ["desc"] [figma-url]  Create a Jira Task matching team conventions (mining + active sprint + preview & approval)
-  /multi-agent:generate-bug ["desc"] [figma-url]   Create a Jira Bug matching team conventions (mining + active sprint + preview & approval)
+  /multi-agent:generate ["desc"] [figma-url] [swagger-url]  Create a Jira Task/Bug/Story matching team conventions (asks type + mining + active sprint + auto-sizing sections + preview & approval)
   /multi-agent:diff-explain   Map a Phase 4 triage finding back to specific diff lines
   /multi-agent:search         Cross-task log search with smart ranking; --semantic queries triage corpus
   /multi-agent:scan           Skill security scan against tiered pattern catalog
@@ -223,8 +222,8 @@ Examples:
   /multi-agent:review
 
   # Create a Jira issue that matches team conventions (preview + approval before create)
-  /multi-agent:generate-task "Profile screen empty state" https://figma.com/design/abc?node-id=1-2
-  /multi-agent:generate-bug "Login crash on iOS 17, see attached log"
+  /multi-agent:generate "Profile screen empty state" https://figma.com/design/abc?node-id=1-2
+  /multi-agent:generate "Login crash on iOS 17, see attached log"
 
 ------------------------------------------------------------
 
@@ -324,8 +323,7 @@ Post-Hoc & Side-Channel:
   /multi-agent:analysis ["analysis-name"]  Feature-spec analizi (Figma + Swagger + Confluence + repolar) → platform başına v3 doküman (23 bölüm Full / 7 bölüm Lite)
   /multi-agent:analysis-resolve [doc]      Analiz dokümanının Bölüm 20 açık sorularını kaynak etiketli adaylarla teker teker çözer
   /multi-agent:build-optimize iOS-only Xcode build performance wrapper → benchmark + analiz + recommend-first .build-benchmark/optimization-plan.md
-  /multi-agent:generate-task ["açıklama"] [figma-url]  Takım standartlarına uygun Jira Task oluştur (convention mining + aktif sprint + önizleme & onay)
-  /multi-agent:generate-bug ["açıklama"] [figma-url]   Takım standartlarına uygun Jira Bug oluştur (convention mining + aktif sprint + önizleme & onay)
+  /multi-agent:generate ["açıklama"] [figma-url] [swagger-url]  Takım standartlarına uygun Jira Task/Bug/Story oluştur (tip sorar + convention mining + aktif sprint + auto-sizing bölümler + önizleme & onay)
   /multi-agent:diff-explain   Phase 4 triage bulgusunu diff satırlarına eşle
   /multi-agent:search         Task log'larında akıllı arama; --semantic triage corpus'unu sorgular
   /multi-agent:scan           Skill güvenlik taraması (tiered pattern catalog)
@@ -436,8 +434,8 @@ Quality & Telemetry (advisory, default açık  -  prefs.global.* ile kapatılabi
   /multi-agent:review
 
   # Takım standartlarına uygun Jira issue oluştur (oluşturmadan önce önizleme + onay)
-  /multi-agent:generate-task "Profil ekranı empty state" https://figma.com/design/abc?node-id=1-2
-  /multi-agent:generate-bug "iOS 17'de login crash, log ekte"
+  /multi-agent:generate "Profil ekranı empty state" https://figma.com/design/abc?node-id=1-2
+  /multi-agent:generate "iOS 17'de login crash, log ekte"
 
 ------------------------------------------------------------
 

package/pipeline/commands/multi-agent/refs/cross-cli-contract.md

@@ -6,12 +6,12 @@
 
 ---
 
-## 1. Command Inventory (37 commands)
+## 1. Command Inventory (36 commands)
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, delete, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, garbage-collect,
-generate-bug, generate-task, help, issue, jira, kill, language, local,
+generate, help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review,
 scan, search, setup, stack, status, sync, test, update
 ```
@@ -19,7 +19,7 @@ scan, search, setup, stack, status, sync, test, update
 Categories:
 
 - **Interactive pickers** (single-purpose, not modes): `jira`, `issue`
-- **Issue generators** (one-shot, no worktree, hard approval gate before create): `generate-task`, `generate-bug`
+- **Issue generator** (one-shot, no worktree, asks type Task/Bug/Story, hard approval gate before create): `generate`
 - **Full 8-phase modes**: `autopilot`, `local`, `local-autopilot`
 - **Fast modes** (Init -> Dev(Opus) -> Commit -> Report): `dev`, `dev-autopilot`, `dev-local`, `dev-local-autopilot`
 - **Tail modes** (run the pipeline tail over already-done local work): `finish`
@@ -30,7 +30,7 @@ Categories:
 
 ### 1.1 Figma component subphase skills
 
-In addition to the 37 top-level multi-agent commands, the figma-to-component pipeline ships platform-specific skills that multi-agent dispatches from Phase 3 (see `refs/component-dispatch.md`). The structure is **platform-parallel iOS + Android with a shared common pool**:
+In addition to the 36 top-level multi-agent commands, the figma-to-component pipeline ships platform-specific skills that multi-agent dispatches from Phase 3 (see `refs/component-dispatch.md`). The structure is **platform-parallel iOS + Android with a shared common pool**:
 
 | Location | Skill count | Purpose |
 |---|---|---|
@@ -312,7 +312,7 @@ For clipboard ops, callers still gate with `if command -v pbpaste >/dev/null; th
 
 This contract is validated by:
 
-- `smoke-cross-cli-behavior.sh`  -  asserts all 37 commands behave identically, pulls from Section 2 (placeholder vocab), Section 5 (argument parsing), Section 6 (output formats); also regression-locks the 6-persona agent deployment
+- `smoke-cross-cli-behavior.sh`  -  asserts all 36 commands behave identically, pulls from Section 2 (placeholder vocab), Section 5 (argument parsing), Section 6 (output formats); also regression-locks the 6-persona agent deployment
 - `smoke-commands-skills-parity.sh` (50 assertions)  -  enforces colon-form command ↔ dash-form skill directory parity
 - `smoke-compliance-skills.sh` (45 assertions)  -  enforces store-compliance skill catalog + 4 consumer wiring
 - `smoke-personal-data.sh`  -  extended in 0.5.5 to treat deprecated placeholders (`{github-username}`, `{your-website}`, `{website-repo}`) as leaks; adds `mmerterden` to public-handle blocklist for generic docs

package/pipeline/commands/multi-agent/refs/features/autopilot-circuit-breaker.md

@@ -0,0 +1,32 @@
+# Feature: Autopilot Circuit-Breaker
+
+**Pattern**: autopilot runs with zero interaction, which is exactly when a silent failure loop is most expensive  -  an agent can burn a budget re-attempting the same broken fix, or thrash between two phases, with nobody watching. A circuit-breaker converts "keep going no matter what" into "keep going until a defined unsafe condition, then halt and hand back to the user." This is the sanctioned autopilot pause (same class as the Phase 7 channels pause): the run stops, records why, and waits for an explicit `resume`.
+
+**Gated by `prefs.global.autopilotCircuitBreaker`** (default: enabled; thresholds tunable). Halting is always safe, so the breaker itself defaults on. Disable per-run only with an explicit override. Complements, does not replace, the existing autopilot safety rules (build-fail max 3 retries, Phase 4 blocking-finding rework, destructive-op confirmations).
+
+## Trip conditions
+
+Any one trips the breaker. All are evaluated from `agent-state.json` + telemetry, no extra model calls.
+
+| # | Trigger | Detection | Default threshold |
+|---|---|---|---|
+| 1 | **No-progress stall** | two consecutive phase checkpoints with no forward transition (same `phase` + `step` + `reworkCount`, no new artifact/commit) | 2 checkpoints |
+| 2 | **Identical repeated failure** | same normalized build-error signature, or the same Phase 4 finding fingerprint, recurs across consecutive Phase 3 rework cycles | 2 cycles |
+| 3 | **Rework storm** | Phase 4 -> Phase 3 rework cycles exceed the cap (distinct from the build-retry cap) | `maxReworkCycles` = 3 |
+| 4 | **Cost drift** | cumulative spend crosses the `costBudget` ceiling, or the projected next-phase spend would exceed it, after model-fallback has already downgraded | `costBudget` ceiling |
+| 5 | **Merge/rebase conflict** | Phase 6 push blocked by a conflict that requires history reconciliation | any conflict |
+
+Trigger 2 is the key addition over the plain build-retry cap: a build can "fail differently" three times (legitimate iteration) or "fail identically" twice (stuck). Only the identical-failure case is a stall; the retry cap catches the rest.
+
+## Action on trip
+
+1. Set `agent-state.json.circuitBreaker = {tripped: true, trigger: <#>, detail, checkpoint}` and flip `autopilot` handling to paused (the run does not continue unattended).
+2. Emit one actionable line per the progress contract: what tripped, the evidence (error signature / cycle count / spend vs ceiling), and the single next action (`resume #N` after a fix, or `kill #N`).
+3. Never auto-resolve the underlying cause  -  no force-anything, no conflict auto-merge, no budget self-raise. The breaker hands control back; it does not paper over the problem.
+4. `resume #N` clears the tripped flag and continues from the recorded checkpoint. If the same trigger fires again immediately, the breaker re-trips (no silent bypass).
+
+## Why this is the right autopilot exception
+
+Autopilot's contract is "no interaction on the happy path." The circuit-breaker fires only off the happy path, where continuing unattended is the *less* safe choice: repeating a proven-broken action, or spending past a ceiling the user set, is not autonomy, it is a runaway. Halting with a precise reason is cheaper than the tokens (and trust) a silent loop burns.
+
+Inspired by autonomous-loop operators that gate on explicit stop conditions (no-progress, identical-stack-trace repetition, cost drift, conflict blocking), adapted to this pipeline's phase/rework/state model.

package/pipeline/commands/multi-agent/refs/generate-issue.md

@@ -1,21 +1,59 @@
-# Generate Issue  -  Shared Flow (generate-task / generate-bug)
+# Generate Issue  -  Shared Flow (generate)
 
-> **TLDR**  -  Shared 11-step flow for `/multi-agent:generate-task` and `/multi-agent:generate-bug`. Mines the target project's existing issues to learn team conventions, detects the active sprint, drafts a standards-compliant issue, asks the user about every genuinely unknown field, renders a full preview, and creates the Jira issue only after explicit approval. Creates exactly one Jira issue per run  -  no branches, no commits, no worktrees.
+> **TLDR**  -  Shared 12-step flow for `/multi-agent:generate`. Asks the issue type (Task / Bug / Story), mines the target project's existing same-type issues to learn team conventions, detects the active sprint, drafts a standards-compliant issue from a fixed standard template with auto-sizing sections, asks the user about every genuinely unknown field, renders a full preview, and creates the Jira issue only after explicit approval. Creates exactly one Jira issue per run  -  no branches, no commits, no worktrees.
 
-Consumed by `generate-task.md` and `generate-bug.md` via their profile blocks (`ISSUE_TYPE`, default description sections, JQL sample filter). This ref is never invoked directly.
+Consumed by `generate.md`. This ref is never invoked directly.
 
 ## Hard rules (must not regress)
 
-- **Approval gate is absolute.** Step [8/11] (full preview + explicit approval) runs on every invocation. There is no autopilot variant of these commands and no preference that skips the gate. `Cancel` means nothing was created.
-- **Never invent content.** Anything the user did not supply and mining could not derive stays an open question (step [7/11]) or an explicitly empty section  -  never fabricated repro steps, environments, or acceptance criteria.
+- **Approval gate is absolute.** Step [9/12] (full preview + explicit approval) runs on every invocation. There is no autopilot variant of this command and no preference that skips the gate. `Cancel` means nothing was created.
+- **Never invent content.** Anything the user did not supply and mining could not derive stays an open question (step [8/12]) or is omitted entirely  -  never fabricated repro steps, environments, acceptance criteria, or test pass/fail results.
+- **Standard template is the baseline.** The description structure comes from the type's standard template (see [7/12]), not from a mined heading set. Mining informs summary prefix, labels, components, priority norm, sprint placement, and test-scenario style  -  never replaces the standard section skeleton.
+- **Auto-sizing.** A conditional section renders only when its trigger is present. No empty placeholder headings  -  if there is nothing to put in a conditional section, it does not appear.
 - **Issue content language follows `prefs.global.outputLanguage`.** Summary and description are written in the user's output language (intentional exception to the "external payloads stay English" default  -  the issue is authored FOR the user's team). Code identifiers, file paths, and URLs stay verbatim. AskUserQuestion `question`/`description` also follow `outputLanguage`; `label`/`header` stay English.
 - **UTF-8 verbatim POST path** (same as `refs/channels/jira.md`): description body goes to a file, `jq -n --rawfile` builds the payload, `curl --data-binary @file` ships it. Never round-trip through `unicode_escape`/`latin-1`, never hand-roll a re-encoding helper. Jira wiki markup (`h3.` headings, `[text|url]` links), real newlines, no HTML entities.
 - **Humanizer pass** on the description body after composition, before the preview render.
-- **Read-only until approval.** Steps 1-8 perform only GET requests. The first write of any kind is the `POST /rest/api/2/issue` in step [9/11].
+- **Read-only until approval.** Steps 1-9 perform only GET requests. The first write of any kind is the `POST /rest/api/2/issue` in step [10/12].
+
+## Standard templates
+
+Each type has a standard section skeleton. `A` = always present. `C` = conditional (renders only when its trigger fires).
+
+| Type | Section | Presence | Trigger (for `C`) |
+|---|---|---|---|
+| **Task** | Detailed Description | A | |
+| | Scope | A | |
+| | Acceptance Criteria | A | |
+| | Test Scenarios | A | populated from mined test-scenario style; skeleton derived from AC when the project has no prior style |
+| | API Contract / Swagger | C | Swagger URL, OpenAPI/contract snippet, or explicit endpoint mention in input |
+| | Design Reference | C | Figma URL given |
+| | Screenshots | C | user pasted image(s) or a Figma screenshot was fetched |
+| | Notes | C | real content only |
+| **Bug** | Detailed Description | A | |
+| | Steps to Reproduce | A | |
+| | Expected Result | A | |
+| | Actual Result | A | |
+| | Environment | A | |
+| | Screenshots / Logs | C | user pasted image(s) or log/stack-trace text |
+| | Regression / Test Scenario | C | derivable from the repro; else omitted |
+| | API Contract | C | API-related bug + Swagger/contract/endpoint given |
+| | Design Reference | C | Figma URL given |
+| | Notes | C | real content only |
+| **Story** | User Story (`As a ... I want ... so that ...`) | A | |
+| | Detailed Description | A | |
+| | Scope | A | |
+| | Acceptance Criteria | A | |
+| | Test Scenarios | A | same as Task |
+| | API Contract / Swagger | C | Swagger URL / contract / endpoint mention |
+| | Design Reference | C | Figma URL given |
+| | Screenshots | C | user pasted image(s) or Figma screenshot fetched |
+| | Dependencies / Notes | C | real content only |
+
+Section headings render in `outputLanguage` (e.g. tr: "Detaylı Açıklama", "Kapsam", "Kabul Kriterleri", "Test Senaryoları", "Adımlar", "Beklenen Sonuç", "Gerçekleşen Sonuç", "Ortam", "Ekran Görüntüleri", "API Contract", "Design Reference", "Notlar").
 
 ## Flow
 
-### [1/11] Pick account (`_account-picker`)
+### [1/12] Pick account (`_account-picker`)
 
 ```bash
 ACCOUNTS=$(~/.claude/lib/account-resolver.sh --providers jira)
@@ -25,7 +63,7 @@ TOKEN=$(~/.claude/lib/credential-store.sh get "$ACCOUNT_JIRA_TOKEN_KEY")
 - Output: `ACCOUNT_JIRA_TOKEN_KEY`, `ACCOUNT_JIRA_HOST`.
 - Token missing/expired → Token Save Flow from `setup.md` inline; user skips → abort, nothing created.
 
-### [2/11] Resolve project key
+### [2/12] Resolve project key
 
 Fallback chain (same as `refs/issue-jira-triad.md` Create path):
 1. `figmaConfig.jira.projectKey` (per-project config, when running inside a configured repo)
@@ -39,44 +77,55 @@ curl -s -H "Authorization: Bearer $TOKEN" \
    AskUserQuestion (single-select) → cache the choice to `prefs.global.defaultJiraKey`.
 - Output: `PROJECT_KEY`.
 
-### [3/11] Parse input
+### [3/12] Pick issue type
+
+AskUserQuestion (single-select, `question` in `outputLanguage`, e.g. tr: "Ne oluşturmak istiyorsun?"): `Task` / `Bug` / `Story`. Never inferred silently.
+- Output: `ISSUE_TYPE`. Selects the standard template from the table above.
+- The chosen type drives the mining JQL in [5/12], the required-field discovery in [5/12], and the section skeleton in [7/12].
+
+### [4/12] Parse input
 
 - Any `figma.com` URL in `$ARGUMENTS` → `FIGMA_URL`. Node-id normalization: `-` → `:`. Branch URLs use `branchKey` as effective `fileKey` (see `rules/figma-pipeline.md` URL parsing).
+- Any OpenAPI/Swagger URL (path or query contains `swagger`, `openapi`, `/v2/api-docs`, `/v3/api-docs`, or a `.json`/`.yaml` spec) → `SWAGGER_URL`.
+- Pasted images (chat attachments) → `USER_SCREENSHOTS[]`. Pasted log/stack-trace text → kept with `FREE_TEXT` and later mapped to the Screenshots / Logs section (Bug) or Notes.
 - Everything else → `FREE_TEXT`.
-- Both empty → AskUserQuestion (free-text, in `outputLanguage`): "Describe the {task|bug} you want to open."
-- `FIGMA_URL` is always optional. Never ask for one; only use it when given.
+- All of `FREE_TEXT`/`FIGMA_URL`/`SWAGGER_URL`/`USER_SCREENSHOTS` empty → AskUserQuestion (free-text, in `outputLanguage`): "Describe the {type} you want to open."
+- `FIGMA_URL`, `SWAGGER_URL`, and screenshots are always optional. Never ask for them; only use them when given.
 
-### [4/11] Convention mining + field discovery + sprint detection (read-only)
+### [5/12] Convention mining + field discovery + sprint detection (read-only)
 
 Three GET groups. Run them before drafting anything.
 
-**4a. Sample recent same-type issues:**
+**5a. Sample recent same-type issues:**
 ```bash
 JQL="project = ${PROJECT_KEY} AND issuetype = ${ISSUE_TYPE} ORDER BY created DESC"
 curl -s -H "Authorization: Bearer $TOKEN" \
-  "https://$ACCOUNT_JIRA_HOST/rest/api/2/search?jql=$(printf '%s' "$JQL" | python3 -c 'import sys,urllib.parse; print(urllib.parse.quote(sys.stdin.read()))')&fields=summary,description,labels,components,priority,fixVersions&maxResults=30"
+  "https://$ACCOUNT_JIRA_HOST/rest/api/2/search?jql=$(printf '%s' "$JQL" | python3 -c 'import sys,urllib.parse; print(urllib.parse.quote(sys.stdin.read()))')&fields=summary,description,labels,components,priority,fixVersions,issuelinks&maxResults=30"
 ```
 Extract from the sample (thresholds are guidance, not hard gates):
-- **Summary prefix pattern**: leading `[...]` or `AREA:` token frequency. Appears in >= 40% of samples → adopt as suggested prefix; top 2-3 prefixes become AskUserQuestion options in step 7 when ambiguous.
-- **Description heading set**: lines matching `h[1-4]\.` or `*bold*` header style, frequency-ranked. A heading set shared by >= 50% of samples overrides the profile's default sections  -  the team template wins.
-- **Top labels / components**: top 5 each by frequency → option lists for step 7.
-- **Priority norm**: modal priority for this issuetype → pre-filled default, editable in preview.
-- **Epic usage rate**: share of sampled issues carrying an epic link → decides whether step 7 asks for an epic.
-
-**4b. Field discovery (createmeta):**
+- **Summary prefix pattern**: leading `[...]` or `AREA:` token frequency. Appears in >= 40% of samples → adopt as suggested prefix; top 2-3 prefixes become AskUserQuestion options in step 8 when ambiguous.
+- **Top labels / components**: top 5 each by frequency → option lists for step 8.
+- **Priority norm**: modal priority for this issuetype → pre-filled default, editable in preview. (Bug priorities often skew higher  -  respect the project's own norm.)
+- **Epic usage rate**: share of sampled issues carrying an epic link → decides whether step 8 asks for an epic.
+- **Test-scenario style** (Task / Story, and Bug regression): detect how the project expresses test scenarios in the sampled descriptions and links, in priority order:
+  1. Linked test issues  -  `issuelinks` pointing at a `Test`-family issuetype (Xray / Zephyr). If present, the standard Test Scenarios section references those linked tests rather than inlining steps.
+  2. A dedicated description heading (`Test Scenarios`, `Test Cases`, `QA`, `Senaryolar`, checklist blocks). If a style is shared by >= 40% of samples, reuse that exact format (heading name + bullet/checklist/table shape).
+  3. No prior style → inline a Test Scenarios skeleton derived from the Acceptance Criteria (one scenario per criterion, Given/When/Then or the project's dominant shape). Skeleton only  -  the user edits it in preview; pass/fail data is never fabricated.
+
+**5b. Field discovery (createmeta):**
 ```bash
 curl -s -H "Authorization: Bearer $TOKEN" \
   "https://$ACCOUNT_JIRA_HOST/rest/api/2/issue/createmeta?projectKeys=${PROJECT_KEY}&issuetypeNames=${ISSUE_TYPE}&expand=projects.issuetypes.fields"
 ```
 - 404 or empty `projects[]` (newer Jira DC deprecates the classic form) → fall back to the paged endpoint: `GET /rest/api/2/issue/createmeta/{PROJECT_KEY}/issuetypes` then `GET /rest/api/2/issue/createmeta/{PROJECT_KEY}/issuetypes/{issuetypeId}`.
-- Every field with `required: true` beyond project/issuetype/summary/description/reporter → step 7 question (options from `allowedValues` when present, free-text fallback).
+- Every field with `required: true` beyond project/issuetype/summary/description/reporter → step 8 question (options from `allowedValues` when present, free-text fallback).
 - Generic custom-field detection by `schema.custom` id  -  never assume field ids:
   - Sprint: `com.pyxis.greenhopper.jira:gh-sprint`
   - Epic Link: `com.pyxis.greenhopper.jira:gh-epic-link`
   - Team-like fields: case-insensitive name match on `Team`
-- 403 → warn "cannot read project field metadata", continue with profile defaults; required fields surface reactively via the 400 path in step 9.
+- 403 → warn "cannot read project field metadata", continue with template defaults; required fields surface reactively via the 400 path in step 10.
 
-**4c. Board + active sprint (Agile REST):**
+**5c. Board + active sprint (Agile REST):**
 ```bash
 curl -s -H "Authorization: Bearer $TOKEN" \
   "https://$ACCOUNT_JIRA_HOST/rest/agile/1.0/board?projectKeyOrId=${PROJECT_KEY}"
@@ -84,58 +133,72 @@ curl -s -H "Authorization: Bearer $TOKEN" \
   "https://$ACCOUNT_JIRA_HOST/rest/agile/1.0/board/${BOARD_ID}/sprint?state=active"
 ```
 - Multiple boards → AskUserQuestion (board name + type). One board → silent. Zero boards or Agile API 404 → the sprint option is silently omitted; the preview notes "backlog only (no board found)".
-- Active sprint found → remember `SPRINT_ID` + name for the step 7 placement choice. None → backlog only; if a `state=future` sprint exists, mention it in the preview as information.
+- Active sprint found → remember `SPRINT_ID` + name for the step 8 placement choice. None → backlog only; if a `state=future` sprint exists, mention it in the preview as information.
 
-### [5/11] Figma context (only when `FIGMA_URL` is set)
+### [6/12] External context (only for the sources actually provided)
 
+Each source is failure-isolated and never blocks issue creation.
+
+**6a. Figma** (only when `FIGMA_URL` is set):
 Follow the 3-tier chain from `rules/figma-pipeline.md`: Tier 1 MCP (`get_design_context` / `get_screenshot`, one re-auth retry) → Tier 2 REST (`keychainMapping.figma_pat`) → Tier 3 ask the user for a screenshot or proceed link-only.
 
 > This command is standalone (same class as `/multi-agent:analysis`), so Figma MCP use here is allowed  -  it is not a dev-phase violation under the "No MCP outside analysis phase" rule.
 
-- Output: frame name, node id, optional screenshot PNG in `/tmp/generate-issue-$$-figma.png` for the step 10 attachment opt-in.
-- Any tier failure degrades gracefully; Figma never blocks issue creation. Link-only is always acceptable.
+- Output: frame name, node id, optional screenshot PNG in `/tmp/generate-issue-$$-figma.png` for the step 11 attachment opt-in.
+- Any tier failure degrades gracefully; link-only is always acceptable.
+
+**6b. Swagger / API contract** (only when `SWAGGER_URL` is set or a contract snippet was pasted):
+- `SWAGGER_URL` set → fetch the spec, then extract **only the referenced endpoints**: if `FREE_TEXT` names specific paths / operationIds / tags, extract those; otherwise summarize the single tag or path group the user pointed at. Never crawl or dump the whole spec.
+```bash
+curl -s "$SWAGGER_URL" -o /tmp/generate-issue-$$-swagger.json  # add auth header only if the user supplied one
+```
+  Parse with `python3`/`jq` to pull, per referenced endpoint: HTTP method + path, a one-line summary, and the key request/response fields (names + types, not the full schema).
+- Only a pasted contract snippet → summarize that snippet (endpoints + key fields).
+- Output: an `API Contract` section body: `{METHOD} {path}` + summary + key request/response fields, plus `[Swagger|{SWAGGER_URL}]` when a URL was given.
+- Fetch failure / unreachable / no matching endpoint → degrade to link-only (or omit the section if nothing usable) and note it in the preview. Never block issue creation.
+
+**6c. Screenshots**: `USER_SCREENSHOTS[]` from step 4 are staged for the step 11 attachment opt-in; each attached image is referenced inline in the relevant section with Jira wiki `!filename|thumbnail!` markup.
 
-### [6/11] Compose draft
+### [7/12] Compose draft
 
-Write summary + description in `outputLanguage`:
+Write summary + description in `outputLanguage` from the type's **standard template** (baseline, not mined headings):
 - **Summary**: `{minedPrefix} {concise title}`, truncated to 255 chars.
-- **Description**: mined heading set from 4a (or the profile's default sections when mining found no dominant template), in Jira wiki markup (`h3.` headings).
-  - Task profile fills: Goal, Scope, Acceptance Criteria, Notes from `FREE_TEXT`.
-  - Bug profile fills: Steps to Reproduce, Expected Result, Actual Result, Environment, Notes from `FREE_TEXT`.
-  - Missing information stays an open question for step 7  -  never invented.
-  - `FIGMA_URL` set → add `h3. Design Reference` with `[Figma|{FIGMA_URL}]` + frame name + node id.
+- **Description**: render the type's standard section skeleton in Jira wiki markup (`h3.` headings), applying auto-sizing:
+  - **Always-present** sections are filled from `FREE_TEXT` (+ mining for Test Scenarios style). If an always-present section has no user content and cannot be derived, it stays an explicit open question for step 8  -  it is not fabricated.
+  - **Conditional** sections render only when their trigger fired (see the Standard templates table): Design Reference when `FIGMA_URL` set (`[Figma|{FIGMA_URL}]` + frame name + node id); API Contract when 6b produced a body; Screenshots when images were staged; Notes/Dependencies only with real content. Otherwise the heading is omitted entirely.
+  - Bug: logs / stack traces / device+OS mentions from `FREE_TEXT` map into Environment and Screenshots / Logs; anything underivable becomes a step-8 question.
 - Run the humanizer skill on the description body.
 - Write the final body to `/tmp/generate-issue-$$.txt` (UTF-8, real newlines) for the `--rawfile` POST.
 
-### [7/11] Clarifying questions (only genuinely unknown fields)
+### [8/12] Clarifying questions (only genuinely unknown fields)
 
 Batched AskUserQuestion(s), each with a "Skip / leave unset" option where Jira allows it:
 - **Component**: mined top components + "none"  -  only when the project uses components.
-- **Epic link**: only when 4a epic usage rate is high. Options from `project = {KEY} AND issuetype = Epic AND statusCategory != Done`.
+- **Epic link**: only when 5a epic usage rate is high. Options from `project = {KEY} AND issuetype = Epic AND statusCategory != Done`.
 - **Priority**: only when the mined norm is ambiguous; otherwise pre-fill the norm and let the preview edit change it.
 - **Labels**: mined top labels, multiSelect.
 - **Assignee**: "me / unassigned / someone else".
 - **Sprint placement**: "Active sprint: {name}" vs "Backlog"  -  only when an active sprint exists.
-- **Required custom fields** from 4b not yet resolved (allowedValues as options).
-- **Bug profile**: Steps to Reproduce or Environment underivable from `FREE_TEXT` → ask here.
+- **Required custom fields** from 5b not yet resolved (allowedValues as options).
+- **Always-present sections still empty**: Bug Steps to Reproduce / Environment, or a Task/Story with no derivable Scope / Acceptance Criteria → ask here.
 
-Rule: never ask about anything already answerable from mining or the input. Regardless of how complete the draft looks, step 8 always runs.
+Rule: never ask about anything already answerable from mining or the input. Regardless of how complete the draft looks, step 9 always runs.
 
-### [8/11] Full preview + approval gate (never skipped)
+### [9/12] Full preview + approval gate (never skipped)
 
-Render the complete issue in chat: project, issuetype, summary, the full description body, priority, labels, components, epic, assignee, sprint/backlog placement, attachment plan (Figma screenshot upload  -  default off, opt-in).
+Render the complete issue in chat: project, issuetype, summary, the full description body, priority, labels, components, epic, assignee, sprint/backlog placement, attachment plan (Figma + user screenshots upload  -  default off, opt-in).
 
 Then AskUserQuestion (`question` in `outputLanguage`, e.g. tr: "Bu sekilde olusturuyorum, onayliyor musun?"):
 
 | Option | Behavior |
 |---|---|
-| `Approve` | Proceed to step 9 |
+| `Approve` | Proceed to step 10 |
 | `Edit` | Free-text "what should change?" → apply → re-render the FULL preview → re-ask. Loop, no iteration cap |
 | `Cancel` | Stop. Nothing was created; say so explicitly |
 
 This gate has no bypass. No flag, mode, or preference suppresses it.
 
-### [9/11] Create
+### [10/12] Create
 
 ```bash
 jq -n --rawfile desc /tmp/generate-issue-$$.txt \
@@ -148,13 +211,13 @@ curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application
   "https://$ACCOUNT_JIRA_HOST/rest/api/2/issue"
 ```
 - Parse `key` from the response → `NEW_KEY`.
-- 400 with field errors → show Jira's per-field error verbatim, return to step 7 for exactly those fields, then re-run step 8 (full preview again).
+- 400 with field errors → show Jira's per-field error verbatim, return to step 8 for exactly those fields, then re-run step 9 (full preview again).
 
-### [10/11] Post-create steps
+### [11/12] Post-create steps
 
 Each step is failure-isolated: on error, warn + continue  -  the issue already exists.
 
-1. **Sprint** (when chosen in step 7/8):
+1. **Sprint** (when chosen in step 8/9):
 ```bash
 jq -n --arg key "$NEW_KEY" '{issues: [$key]}' > /tmp/generate-issue-$$-sprint.json
 curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
@@ -168,30 +231,37 @@ curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application
   -d '{"object":{"url":"'"$FIGMA_URL"'","title":"Figma design"}}' \
   "https://$ACCOUNT_JIRA_HOST/rest/api/2/issue/${NEW_KEY}/remotelink"
 ```
-3. **Screenshot attachment** (only when opted in during preview):
+3. **Swagger remote link** (when `SWAGGER_URL` set):
+```bash
+curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"object":{"url":"'"$SWAGGER_URL"'","title":"API contract"}}' \
+  "https://$ACCOUNT_JIRA_HOST/rest/api/2/issue/${NEW_KEY}/remotelink"
+```
+4. **Screenshot / image attachments** (only when opted in during preview  -  Figma render and/or user-pasted images):
 ```bash
 curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "X-Atlassian-Token: no-check" \
   -F "file=@/tmp/generate-issue-$$-figma.png" \
   "https://$ACCOUNT_JIRA_HOST/rest/api/2/issue/${NEW_KEY}/attachments"
 ```
 
-### [11/11] Report
+### [12/12] Report
 
 ```
 Created {NEW_KEY}: https://{ACCOUNT_JIRA_HOST}/browse/{NEW_KEY}
 ```
-Plus one line per post-create step that ran (sprint placement, remote link, attachment) and any that were skipped with reason.
+Plus one line per post-create step that ran (sprint placement, remote links, attachments) and any that were skipped with reason.
 
 ## Error paths
 
 | Condition | Behavior |
 |---|---|
 | Token missing/expired (401) | Token Save Flow from `setup.md` inline; user skips → abort with message, nothing created |
-| Search 403 / createmeta denied | Warn "cannot read project conventions/fields"; continue with profile-default template; required fields asked reactively on 400 |
-| Zero sampled issues (new project) | Skip mining, use profile defaults, note in preview "no prior issues to learn from" |
+| Search 403 / createmeta denied | Warn "cannot read project conventions/fields"; continue with standard-template defaults; required fields asked reactively on 400 |
+| Zero sampled issues (new project) | Skip mining, use standard template + AC-derived test-scenario skeleton, note in preview "no prior issues to learn from" |
 | Agile API 404 / no boards | Omit sprint choice, backlog implied, say so in preview |
 | No active sprint | Offer backlog only; mention the next `state=future` sprint when one exists |
 | Figma Tier 1 fails | Tier 2; Tier 2 fails → Tier 3 (ask screenshot or link-only). Never block issue creation on Figma |
-| Create 400 (field errors) | Show per-field errors, loop back to step 7 for those fields, re-preview |
+| Swagger fetch fails / unreachable | Degrade to link-only, or omit the API Contract section if nothing usable; note in preview. Never block issue creation |
+| Create 400 (field errors) | Show per-field errors, loop back to step 8 for those fields, re-preview |
 | Create 5xx / network | Show the error, offer one retry, then abort  -  keep `/tmp/generate-issue-$$.txt` and print its path so the draft survives |
 | Post-create step failure | Warn + continue (issue exists); print a manual-fix hint |

package/pipeline/commands/multi-agent/refs/phases/modes.md

@@ -35,6 +35,7 @@ Autopilot mode skips interactive confirmations and runs the pipeline end-to-end
 - Phase 4 Review -> if blocking finding, returns to Phase 3, auto fix + rebuild (safety)
 - Kill/Purge confirmations -> destructive operations always ask
 - Build fail -> auto fix + rebuild (max 3 retries). After 3 retries still failing -> pause, ask user
+- **Circuit-breaker** -> autopilot halts (records reason, waits for `resume`) on a no-progress stall, an identical repeated failure, a rework storm, cost drift past the `costBudget` ceiling, or a merge/rebase conflict. Full wiring: `refs/features/autopilot-circuit-breaker.md`. This is the sanctioned autopilot pause  -  continuing unattended off the happy path is the less safe choice.
 - **Phase 7 channels dispatch** -> always pauses for multi-select. Rationale: Jira/Confluence are externally visible; silently posting wrong-tone content leaks team-visible artifacts. See below.
 
 **State tracking**: `agent-state.json` gets `"autopilot": true`. Autopilot continues on resume as well.

package/pipeline/commands/multi-agent/refs/picker-contract.md

@@ -56,6 +56,6 @@ In autopilot, `ask_choice` resolves to `default` (or the safe first option) with
 
 ## Deterministic gates note
 
-Claude Code's `PreToolUse` exit-2 hook is the one HARD blocking gate: the secret scan runs on every `git commit` and a non-zero exit blocks it. The recommended hook block ships at `install/templates/claude-hooks.json`; `multi-agent:setup` offers to merge it into `~/.claude/settings.json`. Only the secret scan is naturally a PreToolUse hook (it needs no run-specific arguments) - the other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with per-run arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable.
+Claude Code's `PreToolUse` exit-2 hooks are the HARD blocking gates. Two ship, both needing no run-specific arguments so they are naturally hookable: (1) `pre-commit-check.sh` scans the staged diff on every `git commit` and blocks on a detected secret; (2) `agent-guard.sh` runs on `git commit` + `git push` and blocks AI/assistant attribution in a commit message and force-push to a protected branch (main/master/develop). Both are self-contained, fail-open on internal error, and never execute the inspected command. The recommended hook block ships at `install/templates/claude-hooks.json`; `multi-agent:setup` offers to merge it into `~/.claude/settings.json`. The other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with per-run arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable.
 
 Copilot CLI has no `PreToolUse` equivalent, so the secret scan there is workflow-enforced (run as a phase step, not OS-blocked) plus a CI smoke-gate step.