baxian 1.2.21 → 1.2.23

package/dist/skills/baxian-greeting/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: baxian-greeting
+description: One-time startup capability handshake. baxian force-loads this before assigning any task; emit the greeting signal per the baxian-signals skill to prove you can load skills and signal back through your pane.
+disable-model-invocation: true
+---
+
+baxian force-loads this skill once, right after your REPL is ready and before any task is assigned. It verifies you can load a skill, reach the signal protocol, and signal baxian back through your pane.
+
+Do exactly one thing: emit the `greeting` signal, following the **baxian-signals** skill for the wire format and emit rules.
+
+```
+[bx:greeting:<token>]
+```
+
+Substitute `<token>` with the value on the `token:` line of this message and emit the filled signal alone on its own line. Output nothing else.

package/dist/skills/baxian-greeting/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/dist/skills/baxian-pr-feedback/SKILL.md

@@ -1,11 +1,15 @@
 ---
 name: baxian-pr-feedback
-description: Process review feedback on a PR — Fixed/Won't fix each finding, create issues for out-of-scope items
+description: Dev processes PR review feedback (fix phase) and the pre-merge feedback pass (post-approve) — fetch, judge, act, signal back.
 disable-model-invocation: true
 ---
 
+baxian dispatches you with a block of `key: value` dispatch fields. Work in `worktree:`; the PR is in `pr:`. Communicate via the GitHub PR; stay in scope (out-of-scope → new Issue). Route on `phase:`: `fix` → §Fix, `post-approve` → §Post-Approve.
+
 ## Fetch Feedback
 
+Substitute `N` with your `pr:` field:
+
 ```bash
 gh api --paginate repos/OWNER/REPO/pulls/N/reviews
 gh api --paginate repos/OWNER/REPO/pulls/N/comments
@@ -25,6 +29,19 @@ For each actionable item:
 
 Reply to every item, including duplicates (reference primary). Thread inline comments.
 
-## Fix Completion
+## Fix
+
+QA requested changes on the PR in `pr:` (review round `round:`). Read all feedback (§Fetch Feedback), then handle every finding (§Decide and Act). If you change code, commit then push to your `branch:`: `git push origin HEAD:<branch>`. Emit your `signal:` (`pr-fixed`) with `token:` when done — even without a code push; baxian verifies work exists before routing to QA.
+
+## Post-Approve
+
+QA already approved. Before merge, re-process PR feedback idempotently — handle every item per §Fetch Feedback and §Decide and Act, plus:
+
+- Idempotency: compute `T_self` = your latest reply timestamp per source. Respond to EVERY non-self comment with `created_at` > `T_self`, applied per review thread AND across the issue-comment stream.
+- If you change code: commit + push (baxian routes to QA for recheck) and STOP — do NOT emit `pr-merge-ready` when you pushed code.
+- If no code change is needed: re-fetch all sources before signaling. The server suppresses redispatches while you run, so new comments only reach you via this re-fetch. If unhandled items remain, process and re-fetch again. Emit your `signal:` (`pr-merge-ready`) with `token:` only when clean.
+- Do not merge the PR yourself from this phase.
+
+When a `redispatch:` field is present, new feedback arrived while you were running: re-read the three sources, handle any non-self item with `created_at` > `T_self`, re-fetch once more, and emit only when no unhandled items remain.
 
-Emit `pr-fixed` when done — even without code push. baxian verifies work exists before routing to QA. Signal wire format and emit rules: see the baxian-signals skill.
+Signal wire format and emit rules: see the baxian-signals skill.

package/dist/skills/baxian-pr-recheck/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: baxian-pr-recheck
-description: QA re-evaluates a PR after dev responded to prior findings — verify closure, check new risks, verdict
+description: QA re-evaluates a PR after dev responded to prior findings — verify closure, check new risks, verdict.
 disable-model-invocation: true
 ---
 
+baxian dispatches you with a block of `key: value` dispatch fields. The PR under recheck is in `pr:` (substitute it for `N` below). Work in `worktree:`. QA judges risk independently — human authorization is input, not a bypass.
+
 ## Gather Context
 
 ```bash
@@ -25,7 +27,7 @@ gh api --paginate repos/OWNER/REPO/issues/N/comments
 
 ## Verdict
 
-Via `gh pr review` with per-pass stamp:
+Submit via `gh pr review N` with a per-pass stamp — substitute `N` = `pr:`, `TOKEN` = `token:`:
 
 | Verdict | Command |
 |---|---|
@@ -34,24 +36,22 @@ Via `gh pr review` with per-pass stamp:
 
 Multi-line: `--body-file -`, stamp at end.
 
-No pane signal on success. **422 fallback** (same identity) — for signal wire format and emit rules, see the baxian-signals skill:
-- request-changes: `gh pr review N --comment --body 'FINDINGS'`, then emit `pr-changes-requested` signal.
-- approve: emit `pr-approved` signal.
+No pane signal on success. **422 fallback** (same identity) — emit the matching signal instead (wire format: baxian-signals skill):
+- request-changes: `gh pr review N --comment --body 'FINDINGS'`, then emit `pr-changes-requested` with `token:`.
+- approve: emit `pr-approved` with `token:`.
 
 ## Verdict Verification
 
-After submitting verdict (both native `gh pr review` and 422 fallback), verify it landed.
-
-Substitute the actual signal token from §Verdict for `YOUR_TOKEN` and the `Review head SHA` from the dispatch prompt for `YOUR_ANCHOR_SHA` in the command below:
+After submitting (native `gh pr review` or 422 fallback), verify it landed — substitute `TOKEN` = `token:`:
 
 ```bash
 gh api --paginate repos/OWNER/REPO/pulls/N/reviews \
-  --jq '.[] | select((.body // "") | contains("YOUR_TOKEN")) | {id,state,commit_id,submitted_at}'
+  --jq '.[] | select((.body // "") | contains("TOKEN")) | {id,state,commit_id,submitted_at}'
 ```
 
 - **Native path**: must find a review matching ALL of:
-  1. `body` contains the signal token
+  1. `body` contains the token
   2. `state` is `APPROVED` or `CHANGES_REQUESTED`
-  3. `commit_id` equals the Review head SHA (skip this check if the dispatch prompt says the SHA is unavailable)
+  3. `commit_id` equals your `anchor-sha:` field (skip this check when `anchor-sha:` is absent)
 - **422 fallback path**: native review won't exist — verify the pane signal was emitted instead. Do NOT claim a GitHub native review was submitted.
 - If verification fails, report: "verdict 未落到 GitHub，需人工检查" and do NOT claim completion.

package/dist/skills/baxian-pr-review/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: baxian-pr-review
-description: QA performs a full independent pull request review — findings, verdict, approval
+description: QA performs a full independent pull request review — gather context, findings, verdict, verification.
 disable-model-invocation: true
 ---
 
+baxian dispatches you with a block of `key: value` dispatch fields. The PR under review is in `pr:` (substitute it for `N` below). Work in `worktree:`. QA judges risk independently — human authorization is input, not a bypass.
+
 Source of truth: PR, commits, comments, checks, issues.
 
 ## Gather Context
@@ -30,7 +32,7 @@ Inline comments on smallest relevant range. Concrete evidence + expected fix. Do
 
 ## Verdict
 
-Via `gh pr review` with per-pass stamp:
+Submit via `gh pr review N` with a per-pass stamp — substitute `N` = `pr:`, `TOKEN` = `token:`:
 
 | Verdict | Command |
 |---|---|
@@ -39,24 +41,22 @@ Via `gh pr review` with per-pass stamp:
 
 Multi-line: `--body-file -`, stamp at end.
 
-No pane signal on success. **422 fallback** (same identity) — for signal wire format and emit rules, see the baxian-signals skill:
-- request-changes: `gh pr review N --comment --body 'FINDINGS'`, then emit `pr-changes-requested` signal.
-- approve: emit `pr-approved` signal.
+No pane signal on success. **422 fallback** (same identity) — emit the matching signal instead (wire format: baxian-signals skill):
+- request-changes: `gh pr review N --comment --body 'FINDINGS'`, then emit `pr-changes-requested` with `token:`.
+- approve: emit `pr-approved` with `token:`.
 
 ## Verdict Verification
 
-After submitting verdict (both native `gh pr review` and 422 fallback), verify it landed.
-
-Substitute the actual signal token from §Verdict for `YOUR_TOKEN` and the `Review head SHA` from the dispatch prompt for `YOUR_ANCHOR_SHA` in the command below:
+After submitting (native `gh pr review` or 422 fallback), verify it landed — substitute `TOKEN` = `token:`:
 
 ```bash
 gh api --paginate repos/OWNER/REPO/pulls/N/reviews \
-  --jq '.[] | select((.body // "") | contains("YOUR_TOKEN")) | {id,state,commit_id,submitted_at}'
+  --jq '.[] | select((.body // "") | contains("TOKEN")) | {id,state,commit_id,submitted_at}'
 ```
 
 - **Native path**: must find a review matching ALL of:
-  1. `body` contains the signal token
+  1. `body` contains the token
   2. `state` is `APPROVED` or `CHANGES_REQUESTED`
-  3. `commit_id` equals the Review head SHA (skip this check if the dispatch prompt says the SHA is unavailable)
+  3. `commit_id` equals your `anchor-sha:` field (skip this check when `anchor-sha:` is absent)
 - **422 fallback path**: native review won't exist — verify the pane signal was emitted instead. Do NOT claim a GitHub native review was submitted.
 - If verification fails, report: "verdict 未落到 GitHub，需人工检查" and do NOT claim completion.

package/dist/skills/baxian-server-feedback/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: baxian-server-feedback
+description: Dev responds to QA's server-review findings (response.json) and publishes the reviewed branch (server-after-done). Covers code findings, spec findings, and publish.
+disable-model-invocation: true
+---
+
+baxian dispatches you with a block of `key: value` dispatch fields. Work in `worktree:`. Route on `phase:`: `server-feedback` → §Feedback, `server-after-done` → §Publish.
+
+## Feedback
+
+QA's findings ride in the `findings:` block. Judge each finding independently — QA can be wrong; fix only what is actually correct, otherwise reject. Handle EVERY finding by id. The `feedback:` field is `code` or `spec`.
+
+Do NOT push to any remote and do NOT open a PR in this phase — baxian reads your worktree directly; publishing is deferred to the `server-after-done` phase.
+
+For each finding:
+- `fix` — `feedback: code` → change the code (or spec), commit, include the `commitSha` in your response item. `feedback: spec` → revise `.baxian/spec.md` in place. Do NOT commit or push it — baxian reads the file directly.
+- `reject` — concrete rationale why the finding is wrong or not applicable. Never reject just to save effort.
+- `out-of-scope` — rationale plus where it is tracked (issue link or task note).
+
+Write your response to `.baxian/review/response.json` in YOUR worktree (`mkdir -p .baxian/review` first). Atomic write: write `response.json.tmp` first, then `mv response.json.tmp response.json`.
+
+Schema — substitute `<round>` with your `round:` field:
+
+```json
+{"round":<round>,"responses":[{"findingId":"f-1","action":"fix"|"reject"|"out-of-scope","rationale":"..."}]}
+```
+
+Code-finding responses also carry `"commitSha":"..."` on every `fix`. Spec-finding responses omit `commitSha`. Every finding id MUST have exactly one response item (ids may look like `b0-f-1` when the review was batched).
+
+Then emit your `signal:` (`code-fixed` or `spec-fixed`) with `token:`.
+
+## Publish
+
+Publish the reviewed `branch:`:
+- `publish: pr` — `git push -u origin <branch>`, open a managed PR (`gh pr create`; the body MUST end with the `<!-- baxian:managed -->` marker or baxian ignores the PR's merge/comment events; ready for review, not Draft). Emit `code-ready` carrying the new PR number: `[bx:code-ready:<pr_number>:<token>]`.
+- `publish: branch` — `git push -u origin <branch>`, then emit `code-ready` with `token:`.
+
+Signal wire format and emit rules: see the **baxian-signals** skill.

package/dist/skills/baxian-server-feedback/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/dist/skills/baxian-server-review/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: baxian-server-review
+description: QA reviews injected server-review content (a code diff or a spec doc) — judge against the task spec, write findings.json with a verdict. Covers code review, recheck closure, and spec review.
+disable-model-invocation: true
+---
+
+baxian dispatches you with a block of `key: value` dispatch fields; the review input rides in trailing blocks — `diff:` (code) or `spec:` (spec review), plus `prior-findings:` / `prior-response:` on a recheck. Do NOT fetch branches or use `gh` — those blocks ARE the review input. Work in `worktree:`. QA judges risk independently — human authorization is input, not a bypass. If a `content: truncated` field is present, request the missing context via the read-file side-channel.
+
+Route on `phase:`: `server-review` → §Code Review; `server-recheck` → §Code Review + §Recheck Closure; `server-spec-review` → §Spec Review.
+
+## Code Review
+
+Judge the `diff:` block against the task spec: correctness, tests, edge cases, security, regressions.
+
+- Severity: `critical` = broken/unsafe, `major` = must fix before merge, `minor` = improvement.
+- Reference file + line for every code finding.
+- For unchanged files, read them directly from your own base-branch worktree; use the read-file side-channel only for content not present locally.
+
+## Recheck Closure
+
+The `prior-findings:` and `prior-response:` blocks carry the earlier findings and the dev response. Close them out before judging anything new.
+
+- Resolve the status of EVERY prior finding first.
+- A finding the dev claims fixed → verify it in the new diff. No "fixed" without evidence.
+- A finding the dev rejected / called out-of-scope → judge the rationale on merit; re-raise it with concrete counter-evidence if it is wrong.
+- Any prior finding NOT closed reappears in `findings.json` with its ORIGINAL id and the evidence restated — do not renumber or drop it.
+- Verdict `approve` ONLY when every prior finding is closed AND the new diff is clean. An unresolved finding may not be downgraded to a minor suggestion to justify approve — otherwise `request-changes`.
+- After closure, scan the new diff for regressions AND for behavior the fixes introduced that lacks test coverage.
+
+## Spec Review
+
+Judge the `spec:` block:
+
+- completeness — every requirement covered, interfaces and data flows defined, error paths specified.
+- correctness — internally consistent, no contradicting sections, feasible against the existing codebase.
+- ambiguity — any requirement readable two ways is a finding.
+
+Need a referenced file or codebase section to judge feasibility? Use the read-file side-channel. When `prior-findings:` / `prior-response:` blocks are present, verify every finding is closed before judging the rest of the spec.
+
+## Findings Output
+
+Write findings to `.baxian/review/findings.json` in YOUR worktree (`mkdir -p .baxian/review` first). Atomic write: write `findings.json.tmp` first, then `mv findings.json.tmp findings.json`.
+
+Schema — substitute `<round>` with your `round:` field:
+
+```json
+{"round":<round>,"verdict":"approve"|"request-changes","findings":[{"id":"f-1","severity":"critical"|"major"|"minor","message":"...","file":"path","line":N}]}
+```
+
+Spec-review findings use `"location":"Section ..."` in place of `"file"`/`"line"`.
+
+- Finding ids are `f-1`, `f-2`, … sequential and unique within `findings.json` — the dev coverage check and QA closure verification key off them.
+- `approve` MAY carry minor findings as suggestions; the `verdict` field is authoritative.
+
+Then emit your `signal:` (`code-reviewed` or `spec-reviewed`) with `token:`. Signal wire format and the read-file side-channel: see the **baxian-signals** skill.

package/dist/skills/baxian-server-review/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/dist/skills/baxian-signals/SKILL.md

@@ -18,22 +18,28 @@ baxian scans the pane fuzzily (strips ANSI escapes and whitespace), so a TUI sof
 
 ## How to emit
 
-The dispatch prompt hands you a template with placeholders plus the literal values on companion lines:
+The dispatch descriptor names the signal kind in a signal field and the token in `token:`. The default completion is `signal:`; some phases also expose an alternate field for an optional branch (e.g. `spec-signal:` on develop's SDD route). Your phase skill's flow tells you which field applies — emit the one for the route you took, never both:
 
 ```
-[bx:pr-fixed:<token>]
+signal: pr-fixed
 token: a1b2c3d4e5f6
 ```
 
-1. Substitute `<token>` with the value on the `token:` line. `<pr_number>` (only `pr-created`, and `code-ready` when publishing as a PR) is the number of the PR you just created/opened with `gh pr create` — the dispatch prompt carries no PR-number line.
+1. Build the wire form `[bx:KIND:TOKEN]` from the field your skill's flow selects — KIND = that field's value (the `signal:` value by default, or an alternate like `spec-signal:`), TOKEN = the `token:` value — and emit it filled. `<pr_number>` (only `pr-created`, and `code-ready` when publishing as a PR) is the number of the PR you just created/opened with `gh pr create` — the descriptor carries no PR-number field.
 2. Emit the filled signal **alone on its own line**.
-3. **Never echo the `<…>` placeholder verbatim** — the scanner's strict regex cannot match angle-bracket placeholders, so a verbatim template echo fires nothing and the task hangs forever waiting on a signal.
-4. Emit the kind the prompt asks for, **exactly once**, only when its precondition holds. baxian consumes the first matching signal whose token matches the active dispatch; the token rotates every dispatch, so a stale or guessed token never fires.
+3. **Never emit an angle-bracket placeholder** like `[bx:pr-fixed:<token>]` verbatim — the scanner's strict regex cannot match placeholders, so it fires nothing and the task hangs forever waiting on a signal.
+4. Emit the single kind your phase skill's flow selects, **exactly once**, only when its precondition holds. baxian consumes the first matching signal whose token matches the active dispatch; the token rotates every dispatch, so a stale or guessed token never fires.
 
 ## Signal catalog
 
 Phase signals — the per-dispatch transition signals baxian consumes to advance a task. The dispatch prompt always names which one to emit and when.
 
+Bootstrap handshake (before any task):
+
+| Signal | Meaning |
+|---|---|
+| `greeting` | one-time capability check at agent startup; prove you can load this skill and signal back. baxian holds the agent until it sees a valid `greeting` echo |
+
 GitHub PR flow:
 
 | Signal | Meaning |

package/dist/skills/baxian-task-check/SKILL.md

@@ -1,35 +1,50 @@
 ---
 name: baxian-task-check
-description: How to analyze a baxian-managed task before starting development
+description: How a dev analyzes and executes a baxian-managed develop/code task — read the structured prompt, plan, run the develop or code flow, signal back.
 disable-model-invocation: true
 ---
 
-Before writing any code, read the task in your prompt — the `Phase:` / `Role:` header followed by the `Title:` line and its description.
+baxian dispatches you with a block of `key: value` dispatch fields followed by the task `title:` and its description. Work in the directory named by `worktree:` — cd there before any file operation. Route on `phase:`: `develop` → §Develop, `code` → §Code.
 
-## Steps
-1. Read the prompt's `Title:` line and description — the authoritative task source (no `.baxian/task.md` file).
-2. Identify acceptance criteria.
-3. Plan: files to modify, tests to write.
+If an `images:` list is present, read each path (baxian downloaded the user's uploads to the agent host) and factor them into the task.
 
-## What to look for
-- Explicit vs implied requirements
-- Edge cases
-- File/function references
-- Linked docs, screenshots, specs
+## Analyze
 
-## When to ask vs. proceed
+1. Read `title:` and the description — the authoritative task source (no `.baxian/task.md` file).
+2. Identify acceptance criteria, explicit vs implied requirements, edge cases, file/function references, linked docs/specs.
+3. Plan the files to modify and the tests to write.
+
+When to ask vs proceed:
 - Clear → start.
-- Missing info + PR exists → record in PR description.
-- Missing info + no PR → pick reasonable interpretation, write assumption after `<!-- baxian:managed -->` marker (marker MUST be line 1), or create task if blocked.
-- Minor ambiguity → proceed, note in PR.
-- Always record assumptions (PR, task, or commit message).
+- Minor ambiguity → proceed, record the assumption (PR description, task note, or commit message).
+- Blocked → pick a reasonable interpretation and record it after the `<!-- baxian:managed -->` marker (marker MUST be line 1), or create a task if truly blocked.
+
+## Conventions
+
+Your `exchange:` field selects the cross-agent medium:
+- `github-pr` — communicate via the GitHub PR (description, commits, reviews, comments). A managed PR's description first line MUST be `<!-- baxian:managed -->`. Stay in scope — out-of-scope work goes to a new GitHub Issue.
+- `server-files` — baxian reads your worktree directly; do NOT push or open a PR (the publish phase does that). Stay in scope.
+
+A PR you open MUST be ready for review (not Draft): do NOT use `--draft`; if it is draft after creation, run `gh pr ready` before signaling.
+
+## Develop
+
+Two mutually-exclusive routes — pick ONE and emit only its signal:
+
+- **SDD** (only when a `spec-signal:` field is present, i.e. a QA partner exists) — get your design reviewed first: follow §Specification-Driven Development, then emit `spec-signal:` (`spec-done`) with `token:`. Do NOT emit the default `signal:` on this route — that would skip spec review and push an unimplemented task forward. After QA approves the spec, baxian dispatches the code phase. Use SDD when the design is non-trivial; skip it when the change is small or unambiguous.
+- **Direct** — implement the change, then emit `signal:` with `token:`: `exchange: github-pr` → after `gh pr create` (ready for review), emit `pr-created`; `exchange: server-files` → after a local commit (do NOT push), emit `code-done`.
+
+## Code
+
+The spec is approved at `.baxian/spec.md`. Implement it, then emit your `signal:` with `token:`:
+- `exchange: github-pr` → commit + push, `gh pr create` (ready for review), emit `pr-created`.
+- `exchange: server-files` → local commit only (do NOT push, no PR), emit `code-done`.
 
 ## Specification-Driven Development (SDD)
 
-Optional, and offered only when the dispatch prompt gives you a `spec-done` signal (a QA partner exists). Use it to have QA review your design before you write code.
+Use it to have QA review your design before you write code.
 
 - Write the spec to `.baxian/spec.md` in your worktree. Do NOT commit or push it — baxian reads the file directly for QA review.
-- Then emit the `spec-done` signal the prompt gives you (with its token). Signal wire format and emit rules: see the baxian-signals skill.
-- Skip it and implement directly when the change is small or the design is unambiguous.
+- Then emit the `spec-signal:` (`spec-done`) with `token:`.
 
-After QA approves the spec, baxian dispatches the code phase to implement it.
+Signal wire format and emit rules: see the baxian-signals skill.