hatch3r 1.7.0 → 1.7.1

package/README.md

@@ -4,7 +4,7 @@
 
 **Crack the egg. Hatch better agents.**
 
-hatch3r is an open-source CLI and Cursor plugin that installs a battle-tested, tool-agnostic agentic coding setup into any repository. Ship Ready as of Cycle 8 (audit score 83.74/100, 0 Critical findings, 15 platform adapters wired, 20-domain governance audit cycle operational). One command gives you up to 17 agents, 26 skills, 28 rules, 35 commands, and MCP integrations -- optimized for your coding tool of choice. Selective init installs only what you need based on your project type and team size. (Authoritative counts: [`governance/inventory.json`](governance/inventory.json), regenerated by `npm run inventory`.)
+hatch3r is an open-source CLI and Cursor plugin that installs a battle-tested, tool-agnostic agentic coding setup into any repository. Ship Ready as of Cycle 8 (audit score 83.74/100, 0 Critical findings, 15 platform adapters wired, 20-domain governance audit cycle operational). One command gives you up to 17 agents, 26 skills, 28 rules, 37 commands, and MCP integrations -- optimized for your coding tool of choice. Selective init installs only what you need based on your project type and team size. (Authoritative counts: [`governance/inventory.json`](governance/inventory.json), regenerated by `npm run inventory`.)
 
 ## Quick Start
 
@@ -23,7 +23,7 @@ That's it. hatch3r detects your repo, asks about your project context (greenfiel
 | **Agents** | 17 | Code reviewer, test writer, security auditor, implementer (sub-agentic), fixer, researcher, architect, DevOps, and more |
 | **Skills** | 26 | Bug fix, feature implementation, issue workflow, release, incident response, context health, cost tracking, recipes, API spec, CI pipeline, migration, customization, and more |
 | **Rules** | 28 | Code standards, testing, API design, observability, theming, i18n, security patterns, agent orchestration, deep context analysis, and more |
-| **Commands** | 35 | Board management, planning (feature, bug, refactor, test), workflow, quick-change, revision, debug, healthcheck, security-audit, cost-tracking, onboard, benchmark, customization, and more |
+| **Commands** | 37 | Board management, planning (feature, bug, refactor, test), workflow, quick-change, revision, debug, healthcheck, security-audit, cost-tracking, onboard, benchmark, customization, and more |
 | **MCP Servers** | 10 (3 default + 7 opt-in) | Playwright, Context7, Filesystem (default); GitHub, Brave Search, Sentry, Postgres, Linear, Azure DevOps, GitLab (opt-in) |
 | **Platforms** | 3 | GitHub, Azure DevOps, GitLab -- auto-detected from git remote |
 

package/agents/hatch3r-architect.md

@@ -159,7 +159,7 @@ When designing architecture for new modules or services, include error handling
 ## Boundaries
 
 - **Always:** Document decisions in ADRs, evaluate at least 2 alternatives, align with existing patterns, consider migration paths, include error handling in architectural designs
-- **Ask first:** Before proposing architecture that diverges significantly from existing patterns, before introducing new infrastructure dependencies
+- **Ask first:** Before proposing architecture that diverges significantly from existing patterns, before introducing new infrastructure dependencies. When surfacing a question to the user, follow `agents/shared/user-question-protocol.md` (native tool preferred; structured plain-text fallback).
 - **Never:** Make implementation changes (architecture only), skip trade-off analysis, propose solutions without migration paths from current state
 
 ## Example

package/agents/hatch3r-fixer.md

@@ -185,7 +185,7 @@ When producing fix results, be aware that a PARTIAL status with unresolved findi
 ## Boundaries
 
 - **Always:** Fix only Critical and Warning findings, verify quality gates pass, keep changes minimal and targeted, follow the tooling hierarchy (platform CLI > platform MCP, Context7 for libraries, web research for current info)
-- **Ask first:** If a finding is ambiguous or the suggested fix would conflict with acceptance criteria, report BLOCKED with details
+- **Ask first:** If a finding is ambiguous or the suggested fix would conflict with acceptance criteria, report BLOCKED with details. When surfacing a question to the user, follow `agents/shared/user-question-protocol.md` (native tool preferred; structured plain-text fallback).
 - **Never:** Create branches, commits, or PRs. Modify board status. Expand scope beyond reviewer findings. Auto-fix Suggestion items. Skip verification.
 
 </rules>

package/agents/hatch3r-implementer.md

@@ -229,7 +229,7 @@ When encountering errors during implementation, follow these protocols:
 ## Boundaries
 
 - **Always:** Stay within acceptance criteria, write tests, verify quality gates, use stable IDs, follow the tooling hierarchy (platform CLI > platform MCP, Context7 for libraries, web research for current info)
-- **Ask first:** If acceptance criteria are contradictory or unclear, report BLOCKED with details
+- **Ask first:** If acceptance criteria are contradictory or unclear, report BLOCKED with details. When surfacing a question to the user, follow `agents/shared/user-question-protocol.md` (native tool preferred; structured plain-text fallback).
 - **Never:** Create branches, commits, or PRs. Modify board status. Expand scope beyond the issue. Skip tests. Weaken security rules.
 
 </rules>

package/agents/hatch3r-researcher.md

@@ -170,7 +170,7 @@ Every finding must include:
 ## Boundaries
 
 - **Always:** Follow the tooling hierarchy (project docs -> codebase -> Context7 -> web research). Use the platform CLI (check `platform` in `.agents/hatch.json`). Stay within the research brief's scope. Produce structured output matching the mode's specification. Report BLOCKED if the brief is ambiguous or contradictory.
-- **Ask first:** If the brief's scope is unclear, if contradictions are found between sources, or if critical context is missing.
+- **Ask first:** If the brief's scope is unclear, if contradictions are found between sources, or if critical context is missing. When surfacing a question to the user, follow `agents/shared/user-question-protocol.md` (native tool preferred; structured plain-text fallback).
 - **Never:** Create files. Modify code. Create branches, commits, or PRs. Modify board status. Expand scope beyond the research brief. Invent findings not supported by evidence.
 
 </rules>

package/agents/modes/requirements-elicitation.md

@@ -15,6 +15,7 @@ Analyze the task description against the codebase to detect ambiguities, unstate
 
 **Protocol:**
 
+0. Render each elicited question per the format in `agents/shared/user-question-protocol.md` (native tool preferred; structured plain-text fallback otherwise).
 1. Parse the task description for vague language ("improve", "better", "proper", "handle", "support", "clean up", "fix", "update") and flag each instance.
 2. Identify unstated assumptions by comparing the task against the codebase structure — what does the task imply but not state explicitly?
 3. For each of the 10 dimensions below, determine if the task description addresses it. If not, generate a targeted question.

package/agents/shared/quality-charter.md

@@ -38,6 +38,7 @@ Before building anything, verify that the requirements are clear and well-founde
 - If a requirement is ambiguous, ask for clarification rather than guessing.
 - If a requirement seems misguided (solving the wrong problem, using an inappropriate pattern), raise the concern before implementing. Building the wrong thing well is worse than asking a clarifying question.
 - Frame challenges constructively: "Before I implement this, I want to confirm the approach because [specific concern]."
+- When asking, use the platform-native question tool documented in `agents/shared/user-question-protocol.md` rather than free-form prose.
 
 ### 4. Report Root Causes
 

package/agents/shared/user-question-protocol.md

@@ -0,0 +1,95 @@
+---
+id: shared-user-question-protocol
+type: reference
+description: Protocol for how hatch3r agents and commands ask the user clarifying questions — when to ask, native-tool preference, and a plain-text fallback shape.
+tags: [shared, ux, p1, p4]
+cache_friendly: true
+---
+
+## Purpose
+
+This protocol defines how hatch3r agents and commands surface clarifying or triage questions to the user across the 15 supported AI coding platforms. It is the single source of truth for the *how* of asking; the *whether* is governed by [quality-charter §3 "Question Unclear Requirements"](./quality-charter.md) and §8 "Escalate Ambiguity Early". Files that reference this protocol: the requirements-elicitation mode (`agents/modes/requirements-elicitation.md`), the five ASK-checkpoint commands, and the four ask-prone agents — researcher, fixer, architect, implementer.
+
+## When To Ask
+
+- **Ambiguous requirement** — the request maps to two or more reasonable interpretations that produce different code.
+- **Irreversible decision** — deleting data, renaming a public API, dropping a column, force-pushing a branch.
+- **Branching path** — two or more viable approaches with materially different cost, scope, or risk.
+- **Conflicting constraints** — requirements that cannot all hold (e.g., "no new dependencies" and "use library X").
+- **Missing acceptance criteria** — no testable definition of done for the requested change.
+
+## When NOT To Ask
+
+- The user already decided scope in this turn or an earlier turn of the same session.
+- You are in free-text discussion, planning, or a status update — questions belong inside actionable workflows.
+- The answer is verifiable by reading code, running a test, or grepping the repo — verify first, ask only if verification fails.
+- The choice is reversible, low-stakes, and the safer default is obvious — pick the default and note it.
+
+## How To Ask
+
+1. Check whether your target platform exposes a native question or triage tool (see Platform-Native Tool below).
+2. If yes, use the native tool — it produces better UX than free-text replies and is structured for the host runtime.
+3. If no native tool exists on this platform, use the Plain-Text Fallback Template.
+4. Ask at most one question per turn. Bundle related sub-questions into a single multiple-choice prompt rather than firing multiple turns.
+
+## Platform-Native Tool
+
+The marker below is replaced at canonical-write time with the enumeration table generated from `src/pipeline/adapterToolTranslator.ts::ASK_USER_TOOLS`. Look up your runtime platform and follow its row. If your platform's row reads "No documented native tool", use the Plain-Text Fallback Template defined in the next section.
+
+<!-- HATCH3R:PLATFORM-TOOL -->
+
+When viewing this file in the source repo (pre-generation), the marker is unsubstituted — refer to the adapter map in `src/pipeline/adapterToolTranslator.ts` for the same mappings.
+
+## Plain-Text Fallback Template
+
+Use this exact shape when no native tool is available:
+
+```
+**Question:** <one-sentence question stating the choice>
+
+1. <Option A> — <one-line rationale or trade-off>
+2. <Option B> — <one-line rationale or trade-off>
+3. <Option C> — <one-line rationale or trade-off>
+
+Default if no response: <option number, e.g., 2>
+```
+
+Rules for the template:
+
+- Two to four numbered options. One option is too few; five or more signals you have not narrowed the design.
+- Each option carries a one-line trade-off so the user can pick without re-deriving the problem.
+- The default-if-no-response line is mandatory — it removes the deadlock when the user is away or replies "you decide".
+- The default option is the safest reversible choice, not the most ambitious one.
+
+## Examples
+
+**Example 1 — Ambiguous requirement.** Request: "Add caching to the user profile endpoint."
+
+```
+**Question:** Which cache scope matches your needs for the profile endpoint?
+
+1. Per-user, 60s TTL — fastest response, stale data tolerated up to 60s.
+2. Per-user, write-through invalidation — fresh data, +1 cache write per profile update.
+3. Edge cache only — no app changes, but TTL is fixed by the CDN config.
+
+Default if no response: 2
+```
+
+**Example 2 — Branching path.** Request: "Migrate the build to Vite."
+
+```
+**Question:** Should the Vite migration land in one PR or staged behind a feature flag?
+
+1. Single PR — shorter total time, larger blast radius if a regression ships.
+2. Staged with VITE_BUILD flag — two PRs, lets you A/B locally before flipping.
+
+Default if no response: 2
+```
+
+## Anti-Patterns
+
+- **Multi-question barrage** — asking five questions in one turn. Ask the highest-leverage one first; the answer often collapses the rest.
+- **Options-free questions** — "What should I do?" forces the user to design the prompt. Always supply 2–4 candidate options with trade-offs.
+- **Silent assumption** — proceeding when ambiguity is real. Apply quality-charter §8: log the ambiguity in structured output even if you decide to proceed under a default.
+- **Echo-as-question** — restating the user's request back as a question ("So you want me to add caching?"). Confirm only when you have a specific decision point with options to offer.
+- **Inflated default** — choosing the most disruptive option as the no-response default. Defaults must be the reversible, lowest-blast-radius choice.

package/commands/board/shared-azure-devops.md

@@ -156,6 +156,8 @@ After linking, verify via `az boards work-item relation list --id {epic}` and ch
 | Add comments         | `az boards work-item update --id N --discussion "..."`                                         | N/A                    |
 | Create PRs           | `az repos pr create --title "..." --source-branch "..." --target-branch "..."`                 | `create_pull_request`  |
 | Read PR details      | `az repos pr show --id N`                                                                      | N/A                    |
+| Read PR comment threads | `az rest -m GET --url 'https://dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/pullRequests/{N}/threads?api-version=7.1-preview.1'` | N/A |
+| Reply to PR thread   | `az rest -m POST --url '.../pullRequests/{N}/threads/{threadId}/comments?api-version=7.1-preview.1' --body '{"parentCommentId":1,"content":"...","commentType":"text"}'` | N/A |
 | Manage tags          | `az boards work-item update --id N --fields "System.Tags=tag1; tag2"`                          | N/A                    |
 | Board sync           | Work Item State updates (automatic board placement)                                             | N/A                    |
 | CI/Pipelines         | `az pipelines run list` / `az pipelines run show`                                              | N/A                    |

package/commands/board/shared-github.md

@@ -166,9 +166,26 @@ After linking, verify via `issue_read` with `method: get_sub_issues` on the pare
 | Add comments         | `gh issue comment`                                                                                          | `add_issue_comment`                                 |
 | Create PRs           | `gh pr create`                                                                                              | `create_pull_request`                               |
 | Read PR details      | `gh pr view`                                                                                                | `pull_request_read`                                 |
+| Read PR inline comments | `gh api repos/{owner}/{repo}/pulls/{N}/comments --paginate`                                              | `pull_request_read`                                 |
+| Read PR review summaries | `gh api repos/{owner}/{repo}/pulls/{N}/reviews --paginate`                                              | `pull_request_read`                                 |
+| Read PR discussion   | `gh api repos/{owner}/{repo}/issues/{N}/comments --paginate`                                                | `pull_request_read`                                 |
+| Read PR thread resolution | `gh api graphql -f query='{repository(owner:"o",name:"r"){pullRequest(number:N){reviewThreads(first:100){nodes{id,isResolved}}}}}'` | N/A                                |
+| Reply to inline comment | `gh api repos/{owner}/{repo}/pulls/{N}/comments -X POST -F in_reply_to={comment_id} -f body=@{file}`     | N/A                                                 |
+| Comment on PR thread | `gh api repos/{owner}/{repo}/issues/{N}/comments -X POST -f body=@{file}`                                   | `add_issue_comment`                                 |
 | Manage labels        | `gh label create` / `gh label list`                                                                         | `issue_write` (with labels)                         |
 | Projects v2          | `gh project item-add`, `gh project item-edit`, `gh project item-list`, `gh project field-list`, `gh project view` | `projects_write` / `projects_get` / `projects_list` |
 | CI/Actions           | `gh run list` / `gh run view`                                                                               | N/A                                                 |
 | Releases             | `gh release create`                                                                                         | N/A                                                 |
 
 Fallback to MCP only for operations the `gh` CLI cannot handle: sub-issue management (`sub_issue_write`).
+
+### GitHub CLI Field-Typing Notes
+
+`gh api` field flags differ by type. Pass the wrong one and the GitHub REST API returns `HTTP 422: not of type {integer|boolean}`.
+
+| Flag | Type sent | Use for |
+|------|-----------|---------|
+| `-f key=value` | string (URL-encoded form) | `body`, `title`, `commit_message`, `query`, `state`, `event` |
+| `-F key=value` | integer / boolean (auto-typed) — also `@file` for file contents | numeric IDs: `sub_issue_id`, `in_reply_to`, `parent_issue_id`, `issue_number`, `pull_number`, `team_id`, `user_id`, `milestone_number`; booleans: `draft`, `merged`, `auto_merge` |
+
+Sub-issue linking via `POST /repos/{owner}/{repo}/issues/{N}/sub_issues` requires `-F sub_issue_id={child_numeric_id}` — `-f` returns 422. When the `sub_issue_write` MCP is unavailable, write the hand-rolled `gh api` call with `-F`, never `-f`. The same rule applies to PR review-reply (`in_reply_to`), milestone assignment (`milestone_number`), and team membership (`team_id` / `user_id`).

package/commands/board/shared-gitlab.md

@@ -146,6 +146,10 @@ After linking, verify via `glab api projects/{project_id}/issues/{epic_iid}/link
 | Add comments         | `glab issue note N -R {namespace}/{project}`                  | N/A            |
 | Create MRs           | `glab mr create -R {namespace}/{project}`                     | N/A            |
 | Read MR details      | `glab mr view N -R {namespace}/{project}`                     | N/A            |
+| Read MR discussions  | `glab api '/projects/{project_id}/merge_requests/{iid}/discussions?per_page=100' --paginate` | N/A |
+| Read MR notes        | `glab api '/projects/{project_id}/merge_requests/{iid}/notes?per_page=100' --paginate`       | N/A |
+| Reply to discussion  | `glab api '/projects/{project_id}/merge_requests/{iid}/discussions/{discussion_id}/notes' -X POST -f body=@{file}` | N/A |
+| Add MR note          | `glab api '/projects/{project_id}/merge_requests/{iid}/notes' -X POST -f body=@{file}`       | N/A |
 | Manage labels        | `glab label create` / `glab label list`                       | N/A            |
 | Board sync           | Label updates (automatic board list placement)                | N/A            |
 | CI/Pipelines         | `glab ci list` / `glab ci view`                               | N/A            |

package/commands/hatch3r-board-fill.md

@@ -55,7 +55,7 @@ Follow the **Token-Saving Directives** in `hatch3r-board-shared`.
 
 ## Workflow
 
-Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK. For every ASK checkpoint, use the platform-native question tool per `agents/shared/user-question-protocol.md`.
 
 ## Step 0: Triage
 

package/commands/hatch3r-board-pickup.md

@@ -73,7 +73,7 @@ Downstream propagation: every ASK checkpoint that reports verification quality,
 
 ## Workflow
 
-Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK. When asking the user how to proceed, use the platform-native question tool per `agents/shared/user-question-protocol.md`.
 
 ## Step 0: Triage
 

package/commands/hatch3r-board-shared.md

@@ -273,6 +273,27 @@ During **board-fill Step 4c** (external research) and **board-pickup Step 6** (i
 2. Use **web research** for novel technical challenges, current best practices, security advisories, or breaking changes not covered by Context7 or local docs.
 3. Follow the project's tooling hierarchy for knowledge augmentation priority.
 
+### Agent-Synthesized Wrapper Scripts
+
+Board commands instruct the agent to invoke individual CLI / MCP calls; the agent harness already batches them. If the agent synthesises a wrapper shell script anyway, the script MUST be portable across the user's installed shells. macOS ships `bash 3.2` as `/bin/bash` and many users default to `zsh` — bash-4-only features fail loudly on both.
+
+1. **Default to individual tool calls.** Do not wrap `gh issue create`, `gh issue edit`, `gh project item-add`, `az boards work-item create`, or `glab issue create` loops in a synthesised bash script unless the user explicitly asks for a script artifact. The harness's parallel tool dispatch is cheaper than spawning a sub-shell and avoids the portability problem entirely.
+2. **If a wrapper is required, target `bash 3.2` (macOS system default).** Banned constructs: `declare -A` (associative arrays), `${!ARR[@]}` (associative-array key expansion), `mapfile`, `readarray`. Use parallel indexed arrays (`KEYS=()`, `VALUES=()`) with integer indices, or rewrite the batching logic in Python / Node. `zsh` is not a drop-in substitute — `${!ARR[@]}` semantics differ; `bad substitution` is the symptom.
+3. **Pin the shell explicitly.** Start every synthesised script with `#!/usr/bin/env bash` and guard any bash-4+ feature behind `[[ ${BASH_VERSINFO[0]} -ge 4 ]] || { echo "bash 4+ required, found ${BASH_VERSION}"; exit 64; }` so the failure mode is loud, not silent.
+
+### Pager-Bypass Directive
+
+Every `gh api`, `gh pr view`, `gh issue view`, `gh project item-list`, `az pipelines run`, and `glab api` invocation from an agent-driven terminal MUST run with `GH_PAGER=cat` and `PAGER=cat` set. The default GitHub CLI pager (`less`) opens the alternate screen buffer, which returns empty captured output in non-TTY contexts — the call appears to succeed but its `--jq` output is lost. Piping to `| cat` does not bypass the alternate-buffer behaviour; the environment variables are the only reliable workaround.
+
+Set once at the start of every board / PR command run, before the first CLI invocation:
+
+```bash
+export GH_PAGER=cat
+export PAGER=cat
+```
+
+The export is idempotent and safe to re-set. `GH_PAGER` is scoped to `gh`; `PAGER` covers downstream `git`, `az`, or `glab` invocations. This directive applies to every command in this directory tree.
+
 ---
 
 ## Formatting Rules