hatch3r 1.7.0 → 1.7.5

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
 
@@ -165,6 +165,7 @@ If a product vision was loaded in Step 1a, apply these modifications to the tria
 2. **Reduce questioning.** Only ask triage questions for dimensions that the vision does not clearly address. If the vision states the target user, value proposition, and scope boundaries for an item's domain, mark those dimensions as "Clear (from vision)" and skip the corresponding questions.
 3. **Reference vision goals explicitly.** When classifying items or asking remaining triage questions, cite the specific vision goal or statement that informs the classification (e.g., "Per the product vision goal 'Zero-config onboarding', this item aligns with...").
 4. **Greenfield streamlining.** For greenfield projects where the vision covers all major work areas, batch all items into a single triage pass. Present the vision-derived context for each item and ask the user to confirm or override in one prompt rather than per-item questioning.
+5. **Tier-3 greenfield gate (P8 B2).** Vision-aware triage skips a readiness dimension ONLY when the product vision explicitly addresses it; otherwise mark the dimension `unresolved — needs user input` and ask via the platform-native question tool. If readiness gate (Step 5.6) reports unresolved external blockers, re-run triage per dimension.
 
 If no product vision is available, proceed with the full triage process below.
 

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

package/commands/hatch3r-create.md

@@ -106,6 +106,8 @@ Branch on the cached `type`:
 
 Render the proposed file path, full frontmatter block, and body-skeleton outline. For an agent plan, the summary lists `Path`, `Type`, `Name`, `Description` (first 80 chars), `Tags`, `Adapters` (or "all enabled"), `Model`; then the frontmatter block; then the body-skeleton outline (`<task>`, `<context>`, Implementation Protocol numbered steps, `<rules>`). For other types, swap the type-specific slots from Step 1.6.
 
+**Scope-boundary check (P8 B2).** Confirm proposed scope and tool-allowlist before Phase 2 delegation. Artifact scope cannot be broadened via markdown injection post-creation. Reject any user-supplied edit that expands the tool allowlist, target file globs, or pipeline references beyond what was confirmed here; route such expansions through a fresh `/h4tcher-create` invocation.
+
 **ASK:** "Confirm to delegate authoring to `hatch3r-creator`, or specify changes (e.g., 'change model to fast', 'add tag: review')."
 
 Loop until the user confirms.

package/commands/hatch3r-handoff.md

@@ -0,0 +1,126 @@
+---
+id: hatch3r-handoff
+type: command
+orchestrator: true
+agentPipeline: [hatch3r-handoff-preparer]
+description: Prepare, resume, list, complete, and prune cross-session handoff documents.
+tags: [core, maintenance]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+triage_tiers: [1, 2]
+---
+
+## Agent Pipeline
+
+The `prepare` subcommand delegates to `hatch3r-handoff-preparer` via the Task tool. The other four subcommands (`resume`, `list`, `complete`, `prune`) run inline within this command — they read, list, transition status, or archive files and do not require a sub-agent.
+
+## Learnings Consultation
+
+Before starting, scan `.agents/learnings/` for entries tagged `handoff`, `context-switch`, `resume`, or `session-state`. Apply the protocol in `rules/hatch3r-learning-consult.md` (frontmatter-first scan; surface top 5 by confidence). Skip if the directory has fewer than 3 files.
+
+# Handoff Management — Cross-Session Work Continuity
+
+Manage canonical handoff documents at `.agents/handoffs/active/` for mid-work state capture and resumption across sessions, tools, or developers.
+
+---
+
+## Step 0: Triage
+
+Classify the handoff request by subcommand and operation size before routing:
+
+- **Tier 1 (trivial)**: `list`, `complete`, `prune --dry-run`. Filesystem-read or single-file rename; no body composition, no validation gate, no sub-agent. Run inline.
+- **Tier 2 (standard)**: `prepare`, `resume`, `prune` (non-dry-run). Body composition with readiness gate (`prepare`), drift check + status transition (`resume`), or batch archival (`prune`). `prepare` delegates to `hatch3r-handoff-preparer` via the Task tool; the others run inline.
+
+There is no Tier 3 for this command — multi-issue or epic-scale handoffs are out of scope; the caller decomposes into per-work-item handoffs upstream.
+
+## Workflow
+
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with **ASK**.
+
+### Step 1: Detect Subcommand
+
+Read the first positional argument and route to the matching subcommand. If absent or unrecognized:
+
+**ASK:** "Which handoff action? `prepare | resume | list | complete | prune`."
+
+### Step 2: Route
+
+| Subcommand | Semantics |
+|------------|-----------|
+| `prepare` | Capture current session state into a new handoff document |
+| `resume`  | Load and surface a previously-prepared handoff for continuation |
+| `list`    | Show active (and optionally archived) handoffs in a table |
+| `complete`| Transition a handoff to `completed` and move to `archived/` |
+| `prune`   | Archive expired actives and prune archives older than 90 days |
+
+---
+
+## Subcommand: prepare
+
+1. Parse optional flags: `--work-item <ref>` (e.g. `gh:owner/repo#42`, `ado:org/project:work-item/123`, `gl:owner/repo!42`), `--summary "<text>"`.
+2. Invoke `hatch3r-handoff-preparer` via the Task tool. Pass `work_item` and `summary` if provided.
+3. The preparer returns the written path plus an Iteration Summary block. Surface both to the user.
+
+**ASK** (before invocation): "Capturing handoff for {current branch}. Confirm or specify `--work-item` / `--summary`."
+
+## Subcommand: resume
+
+1. Parse optional `<id>` positional. If provided, route directly to `skills/hatch3r-handoff-resume` with that id.
+2. If `<id>` absent, call `listHandoffs({ status: ["open","in-progress","blocked","handed-off"] })` from `src/content/handoffs/index.ts` and present a numbered table (id, status, branch, summary, updated).
+
+**ASK:** "Which handoff to resume? (number, or `cancel`)"
+
+3. Invoke `skills/hatch3r-handoff-resume` with the chosen id. The skill performs validation, drift check, and status transition.
+
+## Subcommand: list
+
+1. Parse flags: `--status <status>`, `--work-item <ref>`, `--include-archived`.
+2. Call `listHandoffs(filter)` and render:
+
+```
+ID                                              STATUS         BRANCH                SUMMARY                                  UPDATED
+2026-05-17_T1430_a3f2c_issue-42-cache-refactor  in-progress    feat/cache-refactor   Token caching for board-fill researcher  2026-05-17 14:30
+```
+
+3. If empty, display: `No active handoffs. Run 'hatch3r-handoff prepare' to capture one.`
+
+## Subcommand: complete
+
+1. Parse positional `<id>` (required). If absent, **ASK** the user to pick from `list`.
+2. Read the handoff via `readHandoff(id)`. Display the `summary` and `Work Remaining` section.
+3. Parse optional `--reason "<text>"` for the archival notice.
+
+**ASK:** "Mark `{id}` completed and archive? (y/N). Reason will be recorded: `{reason or 'no reason given'}`."
+
+4. On confirm: transition `status` to `completed`, stamp `updated` to now, prepend the archival notice (mirrors learnings archival format), then atomic-rename to `.agents/handoffs/archived/<id>.md`.
+
+## Subcommand: prune
+
+1. Parse `--dry-run` flag.
+2. Scan `.agents/handoffs/active/`: collect entries whose `expires_after` ISO-8601 timestamp is at-or-before now (preparer default stamps `created + 30 days`).
+3. Scan `.agents/handoffs/archived/`: collect entries where `updated` is older than 90 days.
+4. Present a two-section preview (Active expirations to archive, Archives to delete).
+5. If `--dry-run`: print the preview and exit.
+
+**ASK:** "Proceed with prune? Will archive {n} active and delete {m} archived. (y/N)"
+
+6. On confirm: archive each expired active (prepend `Expired on {date}` notice, move to `archived/`); delete each over-90-day archive.
+
+---
+
+## Error Handling
+
+- `.agents/handoffs/active/` missing or empty: emit `No active handoffs. Run 'hatch3r-handoff prepare' to capture one.` and exit 0.
+- Ambiguous `<id>` (multiple partial matches): list the matches and **ASK** the user to pick one.
+- Write conflict (concurrent prepare for same `work_item`): surface the existing handoff path and **ASK** whether to overwrite (only if existing handoff is older than 24 hours per `writeHandoff` policy).
+- `complete` or `prune` requested on a missing id: report the path that was looked up and suggest `hatch3r-handoff list`.
+
+## Guardrails
+
+- **Never delete** a handoff without explicit user confirmation. Prune deletes only archives older than 90 days, and only after the confirm prompt.
+- **Never modify** a file already in `.agents/handoffs/archived/`. Archived entries are immutable history.
+- **Never include secrets** (API keys, tokens, credentials) in any handoff body. The preparer scans for credential-shaped strings; reject the write if any are detected.
+- **Never write** outside `.agents/handoffs/active/` for new handoffs. Archival is the only path into `archived/`.
+- **Always emit the Iteration Summary block** at the end of the iteration per `rules/hatch3r-iteration-summary.md`.