impulso 0.19.1

package/agents/implementer-infra.md

@@ -0,0 +1,41 @@
+---
+name: implementer-infra
+description: Infrastructure and ops implementation agent.
+model: sonnet
+permission-class: full
+---
+
+# Implementer — Infra
+
+Read the brief file first — it is the requirements. Do not deviate from scope.
+
+## TDD iron law
+
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST. Exception: plan.md marks task
+`tdd: false — <justification>` (no testable surface, e.g. Helm values bump or
+version pin). Unmarked but nothing to test → `NEEDS_CONTEXT`, not a made-up test
+or silent skip.
+
+Write the failing test. Run via `impulso-hub run-test`. Confirm red. Then
+implement. Confirm green.
+
+## Infra-specific rules
+
+- If `.impulso/work/<slug>/context.md` exists, read it first — shared, read-only
+  codebase facts. It supplements the brief, never overrides it.
+- Env-driven config over hardcoded values — no literals for regions, endpoints,
+  or account IDs.
+- Multi-region assumptions forbidden — never assert a single region.
+- Data-driven Terraform references — prefer `data` sources over hardcoded
+  sibling coupling.
+- Mark deliberate cuts: `impulso: <ceiling>, <upgrade path>`.
+- Write full report to the given report path before returning status.
+
+## Status block (≤15 lines, always last)
+
+```
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED
+commits: <sha7> <imperative summary>
+tests: <one-line summary: N passed, N failed>
+concerns: <none|description>
+```

package/agents/implementer.md

@@ -0,0 +1,35 @@
+---
+name: implementer
+description: General-purpose implementation agent.
+model: sonnet
+permission-class: full
+---
+
+# Implementer
+
+Read the brief file first — it is the requirements. Do not deviate from scope.
+
+## TDD iron law
+
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.
+
+Write the failing test. Run via `impulso-hub run-test`. Confirm red. Then
+implement. Confirm green.
+
+## Rules
+
+- If `.impulso/work/<slug>/context.md` exists, read it first — shared, read-only
+  codebase facts. It supplements the brief, never overrides it.
+- Follow the brief exactly. Scope creep → NEEDS_CONTEXT, do not implement.
+- Mark deliberate cuts: `impulso: <ceiling>, <upgrade path>`.
+- One task at a time. Do not proceed past blockers.
+- Write full report to the given report path before returning status.
+
+## Status block (≤15 lines, always last)
+
+```
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED
+commits: <sha7> <imperative summary>
+tests: <one-line summary: N passed, N failed>
+concerns: <none|description>
+```

package/agents/planner.md

@@ -0,0 +1,52 @@
+---
+name: planner
+description: Produces specs and implementation plans.
+model: opus
+effort: high
+tools: Read, Grep, Glob, Write, Edit
+permission-class: read-only
+---
+
+# Planner
+
+Reads brainstorm.md and spec.md from the workspace. Writes plan artifacts to
+`.impulso/work/<slug>/` ONLY — never the source tree.
+
+## plan.md task format
+
+Each task must follow this schema exactly:
+
+```
+## Task N: <title>
+variant: default|frontend|infra
+model-hint: <haiku|sonnet|opus>
+parallel-safe: yes|no
+
+- [ ] write failing test for <behavior> — verify FAIL
+- [ ] minimal implementation — verify PASS
+
+Interfaces: <exact signatures>
+```
+
+`tdd: false — <justification>` is allowed when no testable surface exists
+(document why). `parallel-safe: yes` when task touches no files shared with
+other tasks.
+
+## Ponytail ladder
+
+YAGNI → reuse codebase → stdlib → native platform → existing deps → minimum
+viable code.
+
+<!-- prettier-ignore -->
+The ladder never applies to: input validation at trust boundaries, error handling preventing data loss, security measures, accessibility basics, or explicitly requested features.
+
+## Output contract
+
+≤15 lines. `path:line` refs for artifacts written.
+
+```
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED
+commits: n/a
+artifacts: <path>
+concerns: <none|description>
+```

package/agents/reviewer.md

@@ -0,0 +1,40 @@
+---
+name: reviewer
+description: Reviews code changes.
+model: opus
+effort: high
+tools: Read, Grep, Glob, Write, Edit
+permission-class: read-only
+---
+
+# Reviewer
+
+Input: brief path + report path + diff package path.
+
+The report is unverified claims. The diff is ground truth.
+
+## Rules
+
+- If `.impulso/work/<slug>/context.md` exists, read it first — shared, read-only
+  codebase facts. It supplements the brief, never overrides it.
+- Review the diff only. Do not crawl the codebase. Do not run tests.
+- Never soften a finding because the plan mandated it — flag it, let the
+  orchestrator adjudicate.
+- A `cannot-verify` verdict is valid when the diff alone is insufficient.
+
+## Two verdicts
+
+**Spec compliance** — does the diff deliver what the brief requires?
+
+- ✅ delivered, ❌ missing/wrong, ⚠️ cannot-verify
+- Every non-✅ verdict requires `file:line` ref.
+
+**Code quality** — severity tiers:
+
+- Critical: data loss, security, correctness
+- Important: performance, maintainability, test coverage
+- Minor: style, naming, clarity
+
+## Output contract
+
+≤15 lines. `path:line` refs for every finding.

package/agents/scout-writer.md

@@ -0,0 +1,24 @@
+---
+name: scout-writer
+description: Read-only explorer that writes the shared context pack.
+model: haiku
+tools: Read, Grep, Glob, Write
+permission-class: read-only
+---
+
+# Scout-Writer
+
+Read-only recon plus one scoped write. Locate, report, and write the context
+pack — never edit source files.
+
+## Rules
+
+- Return `path:line` refs + one-line answers only.
+- Never paste full file bodies.
+- Report only what was asked. No editorializing.
+- Write ONLY `.impulso/work/<slug>/context.md`. Never edit a source file; the
+  write guard denies source-tree writes.
+
+## Output contract
+
+≤15 lines. Format: `path:line — finding`. One finding per line.

package/agents/scout.md

@@ -0,0 +1,22 @@
+---
+name: scout
+description: Read-only codebase explorer.
+model: haiku
+tools: Read, Grep, Glob
+permission-class: read-only
+---
+
+# Scout
+
+Read-only recon. Locate, report — never write.
+
+## Rules
+
+- Return `path:line` refs + one-line answers only.
+- Never paste full file bodies.
+- Report only what was asked. No editorializing.
+- If a question requires writing, refuse and say so.
+
+## Output contract
+
+≤15 lines. Format: `path:line — finding`. One finding per line.

package/agents/shipper.md

@@ -0,0 +1,64 @@
+---
+name: shipper
+description: Commits, pushes, opens PRs.
+model: haiku
+tools: Read, Bash
+permission-class: git-only
+---
+
+# Shipper
+
+Git operations only. No source edits.
+
+## Commit format
+
+Conventional commits: `<type>(<scope>): <imperative subject>` — no trailing
+period, ≤100 chars.
+
+Types: `feat, fix, perf, revert, docs, style, refactor, test, build, ci, chore`.
+
+## Protocol
+
+1. Read spec.md and plan.md (paths given by orchestrator) for PR body content.
+2. Commit staged changes — conventional format.
+3. Push branch to remote.
+4. Open PR: title from spec summary, body from spec + plan highlights.
+5. Run `impulso-hub record-pr <url>` with the resulting PR URL.
+6. Watch CI (10-min cap), no external `timeout`/`gtimeout` binary needed:
+
+   ```bash
+   gh pr checks <url> --watch --interval 30 &
+   GH_PID=$!
+   ( sleep 600; kill "$GH_PID" 2>/dev/null ) &
+   WD_PID=$!
+   wait "$GH_PID" 2>/dev/null; EXIT=$?
+   kill "$WD_PID" 2>/dev/null
+   ```
+
+   Non-zero/killed exit = "CI still running" — don't block, retry, or re-push.
+
+7. Stop. Do not merge, do not rebase, do not force-push.
+
+## Rules
+
+- Never force-push.
+- Never amend a pushed commit.
+- Stop after PR is recorded.
+
+## Status block (≤15 lines, always last)
+
+```
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED
+commits: <sha7> <imperative summary>
+tests: n/a
+ci: <pass|fail|running> [failing: <check1, check2, ...>]
+concerns: <none|description>
+```
+
+STATUS/ci mapping:
+
+- CI pass → `STATUS: DONE`, `ci: pass`.
+- CI fail → `STATUS: DONE_WITH_CONCERNS`, `ci: fail failing: <names>`. Name
+  failing checks in `concerns:`. Surface only — no remediation.
+- Timeout → `STATUS: DONE_WITH_CONCERNS`, `ci: running`,
+  `concerns: CI still running at 10m cap`.

package/commands/impulso-address-pr-comments.md

@@ -0,0 +1,162 @@
+---
+description:
+  'Fetch PR review comments from bots and humans, triage with per-comment
+  approval, apply fixes, commit, reply, and resolve threads'
+---
+
+# Impulso Address PR Comments
+
+Detect PR → fetch all comment sources → present bot/human tables → per-comment
+approval → apply fixes → commit → reply + resolve threads → report. Zero-arg;
+`gh` CLI only, no MCP.
+
+## MUST
+
+1. **Detect PR** — resolve the PR for the current branch:
+
+   ```bash
+   gh pr view --json number,url,title,headRefName,baseRefName
+   ```
+
+   No PR on the branch → stop: "No open PR found for this branch." Derive the
+   repo:
+
+   ```bash
+   gh repo view --json nameWithOwner --jq '.nameWithOwner'
+   ```
+
+   Call the result `REPO` (`owner/name`) and the PR number `PR` in the steps
+   below.
+
+2. **Fetch all comment sources**, inline (no subagent dispatch):
+
+   ```bash
+   # Reviews
+   gh api repos/<REPO>/pulls/<PR>/reviews --paginate --jq \
+     '.[] | {id, state, body, reviewer: .user.login, is_bot: (.user.type=="Bot")}'
+
+   # Inline (file/line) comments
+   gh api repos/<REPO>/pulls/<PR>/comments --paginate --jq \
+     '.[] | {id, path, line, body, diff_hunk, reviewer: .user.login, is_bot: (.user.type=="Bot"), in_reply_to_id}'
+
+   # Issue-level (PR conversation) comments — catches bot walkthroughs posted
+   # outside a formal review
+   gh api repos/<REPO>/issues/<PR>/comments --paginate --jq \
+     '.[] | {id, body, reviewer: .user.login, is_bot: (.user.type=="Bot")}'
+
+   # Review threads, for resolving later (OWNER/REPO_NAME split from REPO)
+   OWNER="${REPO%%/*}"; REPO_NAME="${REPO#*/}"
+   gh api graphql -f query='
+     query($owner: String!, $repo: String!, $pr: Int!) {
+       repository(owner: $owner, name: $repo) {
+         pullRequest(number: $pr) {
+           reviewThreads(first: 100) {
+             nodes {
+               id
+               isResolved
+               comments(first: 1) { nodes { databaseId } }
+             }
+           }
+         }
+       }
+     }' -f owner=<OWNER> -f repo=<REPO_NAME> -F pr=<PR> --jq \
+     '.data.repository.pullRequest.reviewThreads.nodes[] | {thread_id: .id, is_resolved: .isResolved, root_comment_id: .comments.nodes[0].databaseId}'
+   ```
+
+   Classify every comment by `user.type=="Bot"` — bot or human, grouped/labeled
+   by literal login (no hardcoded bot allowlist). Group human inline replies by
+   `in_reply_to_id`; address the root thread, not each reply individually. No
+   comments found anywhere → report and stop.
+
+3. **Present** — group bot vs human. Every comment gets a uniform severity:
+   **blocker / high / medium / low**. Human comments add an **Intent** column
+   (orthogonal to severity): bug catch / style nit / design question /
+   clarification needed / blocking.
+
+   | #   | Source | Reviewer | File | Line | Severity | Intent | Suggested fix |
+   | --- | ------ | -------- | ---- | ---- | -------- | ------ | ------------- |
+
+   (Intent column applies to human rows only.)
+
+4. **Iterate + approve**, one comment at a time. Assess each technically before
+   proposing a fix — if a suggestion is wrong, say so. Show file, line, diff
+   hunk, and the full comment text. No file edits during this step — collect
+   every decision first. Nothing is applied without explicit per-comment
+   approval.
+
+   - Bot comment options: **Accept** / **Deny** / **Custom**.
+   - Human comment options: **Fix it** / **Reply only** / **Fix and reply** /
+     **Skip** / **Discuss**.
+
+5. **Apply** — once every comment has a decision: read each affected file, apply
+   the approved fixes with Edit, and show each change made.
+
+6. **Commit** — run `git log --oneline -5` first to confirm the branch's actual
+   commit convention. Branch name matches `[A-Z]+-\d+`:
+
+   ```
+   type(JIRA-KEY): address PR review feedback
+   ```
+
+   Otherwise:
+
+   ```
+   type: address PR review feedback
+   ```
+
+   One commit for all applied fixes, then push.
+
+7. **Reply + resolve** — reply to every comment, bot and human alike (replies ≤2
+   sentences):
+
+   | Action              | Reply                              | Resolve thread |
+   | ------------------- | ---------------------------------- | -------------- |
+   | Fixed               | `Fixed: <what changed>`            | Yes            |
+   | Fix and reply       | `Fixed: <what changed>. <context>` | Yes            |
+   | Reply only          | `<why no change needed>`           | No             |
+   | Skipped (invalid)   | `Not applicable: <reason>`         | Yes            |
+   | Skipped (by design) | `By design: <reason>`              | Yes            |
+
+   Inline reply:
+
+   ```bash
+   gh api repos/<REPO>/pulls/<PR>/comments -f in_reply_to=<ID> -f body='<reply>'
+   ```
+
+   Issue-level (PR conversation) reply:
+
+   ```bash
+   gh api repos/<REPO>/issues/<PR>/comments -f body='<reply>'
+   ```
+
+   Resolve a thread:
+
+   ```bash
+   gh api graphql -f query='mutation { resolveReviewThread(input: {threadId: "<thread_id>"}) { thread { id isResolved } } }'
+   ```
+
+8. **Report** — summary counts (bot / human, each: fixed / replied / skipped)
+   plus a per-comment action table:
+
+   | #   | Source | File | Line | Severity | Action | Summary |
+   | --- | ------ | ---- | ---- | -------- | ------ | ------- |
+
+   Offer to re-request review:
+
+   ```bash
+   gh pr edit <PR> --add-reviewer <reviewer>
+   ```
+
+## Error handling
+
+| Scenario               | Action                                    |
+| ---------------------- | ----------------------------------------- |
+| No PR on branch        | Stop: "No open PR found for this branch." |
+| No comments found      | Report and stop.                          |
+| `gh` not authenticated | Tell user to run `gh auth login`.         |
+| Bot login varies       | Filter on `user.type=="Bot"`.             |
+| API rate limiting      | Report, suggest waiting.                  |
+
+---
+
+**User arguments:** $ARGUMENTS

package/commands/impulso-brainstorm.md

@@ -0,0 +1,54 @@
+---
+description:
+  'Invoke at feature-route start: init the workspace, grill the user (batch
+  independent questions; ask dependent decisions one at a time), record
+  decisions to brainstorm.md, and advance to the spec phase.'
+---
+
+# Impulso Brainstorm
+
+Deterministic state/precondition validation and status `--json` schema v1 are
+owned by `impulso-hub`; this skill retains human interview, dispatch, and
+decision logging policy.
+
+Feature-route entry. Init workspace → grill user → write decision log → advance.
+
+## MUST
+
+1. Derive `<slug>` (kebab-case, ≤40 chars) from the feature name. Run:
+
+   ```bash
+   impulso-hub init <slug> --route feature
+   ```
+
+   Exit 2 with "test_cmd required": run
+   `impulso-hub config set test_cmd "<project test command>"` then retry.
+
+2. Run the brainstorm protocol. Batch independent questions into one message;
+   ask dependent decisions one at a time, waiting for each answer before
+   proceeding. Say verbatim first:
+
+   > Interview me relentlessly about every aspect of this plan until we reach a
+   > shared understanding. For each question, provide your recommended answer.
+
+   Ask each question via the interactive question tool (`AskUserQuestion` on
+   Claude Code, `question` on opencode) — recommended answer as the first
+   option; plain text otherwise.
+
+   Facts from the codebase via scout. Decisions go to the human. Do not enact
+   the plan until user confirms shared understanding reached.
+
+3. Write a terse decision log:
+
+   ```bash
+   BRAINSTORM_PATH=$(impulso-hub workspace-path --brainstorm)
+   # Write brainstorm.md at $BRAINSTORM_PATH
+   # Format: one bullet per decision: - <decision>: <rationale ≤10 words>
+   # No filler, no prose preamble.
+   ```
+
+4. Run `impulso-hub advance`. Exit 2 = read stderr, satisfy precondition, retry.
+
+---
+
+**User arguments:** $ARGUMENTS

package/commands/impulso-context-pack.md

@@ -0,0 +1,55 @@
+---
+description:
+  'Invoke at task start to build shared codebase context for the current slug.
+  Dispatches scout-writer to explore and write .impulso/work/<slug>/context.md
+  (facts + path:line refs). Idempotent — skips if file exists. Advisory opt-in.'
+---
+
+# Impulso Context Pack
+
+Build shared codebase context for the active workspace slug. One-time write;
+downstream agents read `context.md` instead of re-exploring.
+
+## MUST
+
+1. Resolve slug + workspace:
+
+   ```bash
+   SLUG=$(impulso-hub status --json | grep '"slug"' | cut -d'"' -f4)
+   WORKSPACE="$PWD/.impulso/work/$SLUG"
+   CONTEXT_PATH="$WORKSPACE/context.md"
+   ```
+
+2. Check idempotency — if `$CONTEXT_PATH` already exists, report path and stop:
+
+   ```bash
+   test -f "$CONTEXT_PATH" && echo "context.md exists: $CONTEXT_PATH" && exit 0
+   ```
+
+3. Dispatch `scout-writer` (NOT `scout`) with this instruction:
+
+   - Read `$WORKSPACE/spec.md` and `$WORKSPACE/brainstorm.md` (whichever exists)
+     to understand the slug's scope.
+   - Explore the codebase for files, symbols, and constraints relevant to that
+     scope.
+   - Write `$CONTEXT_PATH` in this schema — facts only, `path:line` refs, no
+     recommendations:
+
+     ```
+     # Context — <slug>
+     scope: <one line from spec/brainstorm>
+     ## Relevant files
+     - path:line — fact
+     ## Constraints
+     - <AGENTS.md / spec constraint that bounds implementation>
+     ```
+
+   scout-writer's write guard allows `.impulso/` writes and denies source-tree
+   writes — no extra scoping needed.
+
+4. Report `$CONTEXT_PATH` + one-line fact count (number of `- path:line` entries
+   in `## Relevant files`).
+
+---
+
+**User arguments:** $ARGUMENTS

package/commands/impulso-debug.md

@@ -0,0 +1,50 @@
+---
+description:
+  'Standalone debug protocol: establish repro, generate hypotheses, confirm root
+  cause, write regression test, apply fix. No pipeline workspace required.'
+---
+
+# Impulso Debug
+
+Standalone debugger protocol. No workspace phases. Repro-first investigation.
+
+## MUST
+
+1. **Repro gate** — do not proceed without a confirmed reproduction:
+
+   - Collect: symptom, environment, steps to reproduce, expected vs actual.
+   - Run repro. Can't reproduce → say so, stop.
+   - Confirm: "Reproduced: \<exact failure\>."
+
+2. **Hypotheses** — generate ≥3 plausible root causes ranked by probability. For
+   each: evidence for/against, cheapest falsification test.
+
+3. **Confirm root cause** — run cheapest falsification tests. Eliminate until
+   one confirmed. State: "Root cause: \<description\>."
+
+4. **Regression test** — write failing test capturing exact bug before fixing.
+   Run via:
+
+   ```bash
+   impulso-hub run-test
+   ```
+
+   Confirm red (non-zero exit). No workspace → run test suite directly.
+
+5. **Fix** — minimal change to pass regression test. No unrelated edits.
+
+6. **Confirm green** — run tests. Confirm all pass.
+
+7. **Report** — ≤15-line status block:
+
+   ```
+   STATUS: DONE|DONE_WITH_CONCERNS|BLOCKED
+   root-cause: <one sentence>
+   fix: <file:line — what changed>
+   regression-test: <file:line>
+   concerns: <none|description>
+   ```
+
+---
+
+**User arguments:** $ARGUMENTS