hatch3r 1.7.0 → 1.7.5

package/commands/hatch3r-quick-change.md

@@ -95,7 +95,7 @@ If Tier 1, run inline. If Tier 2, run the implementer-only pipeline below. If Ti
 
 ## 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 1: Input and Batch Parsing
 
@@ -130,9 +130,9 @@ Aggregate across the batch for total estimated scope.
 
 **Hard block — Tier 3 (Deep):** If any item scores Tier 3, quick-change is not appropriate.
 
-**ASK:** "This change scores Tier 3 (Deep complexity): {reason}. Quick-change does not provide the research depth needed. Options: (a) switch to `hatch3r-workflow`, (b) narrow the scope."
+**ASK:** "This change scores Tier 3 (Deep complexity): {reason}. Quick-change does not provide the research depth needed. Options: (a) switch to `/h4tcher-workflow`, (b) narrow the scope."
 
-Do NOT offer a "proceed anyway" option for Tier 3. The user must switch to workflow or narrow scope.
+Do NOT offer a "proceed anyway" option for Tier 3. The user must switch to `/h4tcher-workflow` or narrow scope.
 
 **Soft guard — Tier 2 (Standard) or threshold triggers:** If any item scores Tier 2, or if any of these threshold triggers fire (any one is sufficient):
 - Estimated total exceeds **5 files**
@@ -140,6 +140,8 @@ Do NOT offer a "proceed anyway" option for Tier 3. The user must switch to workf
 - Changes touch security-sensitive areas
 - Changes require new dependencies or architectural decisions
 
+**Threshold gate (P8 B2).** If any threshold trigger fires (>3 files, cross-module touch, schema change, or net new dependency), spawn the `hatch3r-researcher` with `requirements-elicitation:quick` mode IMMEDIATELY in Step 4b — do not defer research to discover scope creep mid-implementation. Tier-3 hard-block remains in effect.
+
 **ASK:** "This looks larger than a quick change: {reason}. Options: (a) proceed with lightweight research, (b) switch to `hatch3r-workflow` for full ceremony, (c) narrow the scope."
 
 If no threshold is triggered and all items are Tier 1, present the change list:

package/commands/hatch3r-report.md

@@ -0,0 +1,167 @@
+---
+id: hatch3r-report
+type: command
+orchestrator: false
+description: Generate an in-chat session report from the active or named transcript — every tool call, sub-agent delegation, and file edit, with diagnostics for missed parallelism, redundant work, and over-serialization.
+tags: [maintenance]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+---
+## Agent Pipeline
+
+This command runs inline and does not spawn sub-agents. Parsing is driven by Bash + jq over the on-disk session transcript; the LLM only sees aggregated counts and triggered-heuristic evidence, never the raw JSONL. This keeps the command efficient (P7) even on 1000+ record sessions.
+
+# Session Report — Agentic Action Replay
+
+Render an in-chat report of what happened in a Claude Code session: every tool call, every sub-agent `Agent` delegation, every file edit, every hook event. Default = current session, executive summary, in-chat. Flags extend scope and depth. Two audiences: (a) users who want to understand the session end-to-end; (b) maintainers investigating runtime shape for framework-level optimizations.
+
+---
+
+## Argument Parsing
+
+| Flag | Effect |
+|------|--------|
+| `--session <id\|path>` | Target a UUID under the project slug dir, or an absolute `.jsonl` path. Default = newest-mtime jsonl in current project slug. |
+| `--list` | Exclusive. Print the 5 most-recent sessions in this project (sessionId, mtime, first-user-message preview 60 chars). Skips all other rendering. |
+| `--verbose` | Append a chronological per-turn timeline after the executive summary. |
+| `--save` | After rendering in-chat, also write to `.hatch3r/reports/{sessionId-short8}-{YYYYMMDD-HHMMSS}.md`. |
+
+`--list` takes precedence over `--session`, `--verbose`, `--save`. All other flags compose.
+
+## Step 1 — Discover the Session
+
+Compute the project slug from the working directory: `SLUG="$(pwd | sed 's|/|-|g')"`. The transcript directory is `~/.claude/projects/${SLUG}`. List `*.jsonl` files; the active session is the newest by mtime (`ls -t *.jsonl | head -1`). When `--session <value>` is provided, resolve a 36-char UUID against the slug dir as `${value}.jsonl`, otherwise treat as an absolute path. When `--list` is set, enumerate the top-5 newest jsonl files; for each, parse the first `type=user` record and emit `<short-id>  <mtime>  <first-60-chars-of-user-text>`.
+
+## Step 2 — Aggregate via jq
+
+Run jq over the JSONL to produce a single structured JSON of counts. Persist to `$(mktemp)` so the LLM reads aggregated data only. Sample pipeline:
+
+```bash
+jq -s '
+  def tu: [.[] | select(.message.content?) | .message.content[] | select(.type=="tool_use")];
+  def tr: [.[] | select(.message.content?) | .message.content[] | select(.type=="tool_result")];
+  def asst_turns: [.[] | select(.type=="assistant" and (.message.content?))];
+  def thinks: [.[] | select(.message.content?) | .message.content[] | select(.type=="thinking") | .text];
+  {
+    sessionId: .[0].sessionId, firstTs: .[0].timestamp, lastTs: .[-1].timestamp,
+    cwd: .[0].cwd, gitBranch: .[0].gitBranch, records: length,
+    toolCounts: (tu | group_by(.name) | map({tool: .[0].name, count: length}) | sort_by(-.count)),
+    distinctReads: (tu | map(select(.name=="Read") | .input.file_path) | unique | length),
+    distinctEdits: (tu | map(select(.name=="Edit" or .name=="Write") | .input.file_path) | unique | length),
+    topReads: (tu | map(select(.name=="Read") | .input.file_path) | group_by(.) | map({path: .[0], count: length}) | sort_by(-.count) | .[0:3]),
+    agentCalls: (tu | map(select(.name=="Agent") | {sub: (.input.subagent_type // "general-purpose"), prompt: (.input.prompt[:80] // "")})),
+    bashCmds: (tu | map(select(.name=="Bash") | .input.command)),
+    turnLens: [asst_turns[] | (.message.content | map(select(.type=="tool_use")) | length)],
+    thinkingChars: ([thinks[] | length] | add // 0),
+    errorResults: (tr | map(select((.content | tostring) | test("error|failed"; "i"))) | length),
+    totalResults: (tr | length)
+  }' "$JSONL"
+```
+
+`thinkingChars` is the summed length of every `thinking` block's text — required input for D-LOOP-01 (`thinking chars ÷ (tool_use count + 1) > 1200`).
+
+The LLM reads the resulting JSON, computes derived metrics (parallel-batch count = turns with ≥2 tool_use; sequential count = turns with exactly 1), and builds the rendered tables.
+
+## Step 3 — Compute Diagnostics
+
+Apply each rule in §Diagnostic Heuristics over the aggregated structure. Each fired diagnostic produces a record `{id, severity, turns:[...], evidence, suggestion}`. Emit at most one fire per rule per session (consolidate same-rule fires across turns into one record). If zero rules fire, render `None — execution shape is clean.`
+
+## Step 4 — Render Executive Summary
+
+Always emit. Headings, order, and content per §Output Format. Mask obvious secret patterns (`sk-...`, `ghp_...`, `xoxb-...`, `AIza...`, `Bearer ...`) in any rendered tool_use input field. Truncate Bash commands and Agent prompts to ≤80 chars in tables.
+
+## Step 5 — Render Verbose Timeline (--verbose only)
+
+Append `## Timeline`. For each assistant turn containing ≥1 tool_use, emit a numbered block: turn index, ISO timestamp, elapsed-since-start, optional `thinking: N chars` summary, one line per tool_use (tool name + first 60 chars of primary input field), and a parallel/sequential marker — `→ {n} tool_use blocks ✓ parallel` when n≥2, `→ 1 tool_use ⚠ sequential` when n=1.
+
+## Step 6 — Save to Disk (--save only)
+
+Create `.hatch3r/reports/` if missing. Write the rendered markdown (executive summary + timeline if `--verbose` set) to `.hatch3r/reports/{sessionId-short8}-{YYYYMMDD-HHMMSS}.md`. Append a `## Raw Counts (machine-readable)` section containing the jq-aggregated JSON in a fenced ```json``` block — this lets future tooling grep across sessions without re-parsing the source JSONL. Print the file path back to chat. The `.hatch3r/` directory is gitignored.
+
+---
+
+## Output Format
+
+```markdown
+## Session Report — a5d750f7
+
+**Window:** 2026-05-12 09:14:03 → 09:47:21 (33m 18s, 272 records)
+**Project:** hatch3r (release/1.7.1)
+
+### Tool Activity (91 tool calls)
+
+| Tool | Calls | Notable |
+|------|------:|---------|
+| Read | 47 | 12 distinct files; validate.ts read 4x |
+| Bash | 21 | 6 parallel batches, 15 sequential |
+| Edit | 18 | 9 distinct files |
+| Task |  4 | 3 general-purpose, 1 explore — all sequential |
+| Grep |  1 | — |
+
+### Sub-Agent Delegation (4 Agent calls)
+
+| # | Subagent | Prompt (first 60) | Files touched |
+|---|----------|-------------------|---------------|
+| 1 | general-purpose | "Find references to validateCommandOrch..." | 0 |
+| 2 | Explore | "Map existing commands that overlap..." | 0 |
+| 3 | Explore | "Find conversation transcript access..." | 0 |
+| 4 | Plan | "Design hatch3r-report command..." | 0 |
+
+### File Footprint
+
+- 12 distinct files read; 9 distinct files edited
+- Top 3 most-read: src/cli/commands/validate.ts (4x), commands/hatch3r-context-health.md (2x), CHANGELOG.md (2x)
+
+### Diagnostics
+
+- WARN D-PAR-01 Missed parallelism: turns 7, 9, 11 each issued one Read on disjoint paths → batch into one assistant turn.
+- WARN D-RED-01 Redundant Read: src/cli/commands/validate.ts read at turns 4, 8, 22, 31 with no Edit between turns 4 and 31.
+- INFO D-PAR-02 Sub-agent fan-out: 4 Agent calls at turns 44, 53, 67, 78 — disjoint subsystems → eligible for parallel fan-out.
+
+### Suggested Next Action
+
+Re-run `/hatch3r-report --verbose` for the chronological timeline.
+```
+
+---
+
+## Diagnostic Heuristics
+
+| ID | Heuristic | Trigger | Severity |
+|----|-----------|---------|----------|
+| D-PAR-01 | Missed parallelism (same-tool sequential) | ≥3 consecutive assistant turns each with exactly 1 `tool_use` of the **same** tool type targeting disjoint inputs | WARN |
+| D-PAR-02 | Sub-agent fan-out missed | ≥2 `Agent` tool_use blocks within 10 turns where prompt subjects target disjoint path prefixes | WARN |
+| D-RED-01 | Redundant Read | Same `Read.file_path` in ≥3 tool_use blocks with no intervening `Edit`/`Write` on that path | WARN |
+| D-RED-02 | Re-Bash identical command | Same `Bash.command` (trimmed exact match) ≥2 times within 20 turns | INFO |
+| D-LOOP-01 | High thinking-to-action ratio | Total `thinking` chars ÷ (tool_use count + 1) > 1200 AND tool_use count < 8 | WARN |
+| D-LOOP-02 | Tool burst → stall | One turn with ≥5 tool_use blocks AND next turn with 0 AND ≥3 subsequent turns with 0 tool_use | INFO |
+| D-ERR-01 | Tool-result error rate | `tool_result.content` matches `/error\|failed/i` in >20% of results | WARN |
+| D-PATH-01 | File staleness | Path read at turn N, edited at turn M, re-read at turn P>M+15 with no intervening edit on that path | INFO |
+| D-SUB-01 | Sub-agent returning empty | `Agent` tool_result body <200 chars AND no subsequent Edit on any path the prompt referenced | WARN |
+
+Each fired record: `{id, severity, turns:[n,...], evidence, suggestion}`. Consolidate same-rule fires into one record per session.
+
+---
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| `~/.claude/projects/{slug}` does not exist | Print: "No Claude Code transcripts found for this project. Slug: {slug}". Exit. |
+| Slug dir exists but contains no `*.jsonl` | Print: "Project directory empty — no sessions to report on." Exit. |
+| `--session <id>` does not resolve to a readable file | Print: "Session {id} not found under {slug}. Use --list to see available sessions." Exit. |
+| `jq` not installed | Print: "jq is required. Install via `brew install jq` (macOS) or your distro's package manager, then retry." Exit. |
+| Malformed JSONL record encountered | Skip the record; increment a `skipped` counter; surface the count in the executive summary footer when non-zero. |
+| Read access denied to a transcript file | Print: "Cannot read {path}: permission denied." Exit. |
+
+---
+
+## Guardrails
+
+- **Never modify the JSONL.** Read-only access. All scratch files go to `$(mktemp)` and are deleted at end-of-run.
+- **Mask obvious secret patterns** (`sk-`, `ghp_`, `xoxb-`, `AIza`, `Bearer `) in any rendered tool_use input — substitute `{REDACTED-{prefix}}`. The transcript may contain ephemeral tokens from user pastes.
+- **Never write outside `.hatch3r/reports/`.** The `--save` target is fixed; do not honor flags or env vars that redirect output to other paths.
+- **Never abort on a malformed record.** Skip-and-count is the contract; aborting would hide the rest of the session from the operator (Silent Failure Contract — surface the skip count rather than swallowing it).
+- **Honor the iteration summary contract** (`rules/hatch3r-iteration-summary.md`) at the end of the parent assistant turn that invoked this command. The report content is not a substitute for the canonical Status / Outcome / Done block.

package/commands/hatch3r-revision.md

@@ -145,7 +145,7 @@ Revision Context:
 
 **ASK:** "Is this the work you want to revise? Any additional context I should know about? (yes / provide context / wrong branch)"
 
-If the user provides additional context (e.g., a different issue number, clarifications, or scope adjustments), incorporate it before proceeding.
+When asking, use the platform-native question tool per `agents/shared/user-question-protocol.md`. If the user provides additional context (e.g., a different issue number, clarifications, or scope adjustments), incorporate it before proceeding.
 
 ---
 

package/commands/hatch3r-workflow.md

@@ -77,7 +77,7 @@ If Tier 1, take Quick Mode with reduced sub-agent prompts. If Tier 2, take Quick
 
 ## 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 (Scale-Adaptive Mode Selection)
 
@@ -176,6 +176,8 @@ Task Analysis:
 
 **Goal:** Design the solution before implementing.
 
+**Research-completeness directive (P8 B2).** If the Plan phase discovers unknowns not covered by Phase 1 research, spawn additional researcher modes before Phase 3 (Implementation). Do not defer research unknowns to implementation time. Spawning more researcher sub-agents is cheaper than discovered rework.
+
 #### 2a. Draft Implementation Plan
 
 1. List all files to create or modify.