@jaggerxtrm/specialists 3.16.0 → 3.17.0

package/README.md

@@ -170,8 +170,10 @@ Useful commands:
 ```bash
 sp ps                         # actionable dashboard
 sp ps -f                      # TTY dashboard follow; pipes emit ANSI-free snapshots
-sp feed <job-id>              # full DB-backed event replay
+sp feed <job-id>              # compact DB-backed event replay
 sp feed -f                    # follow all active jobs
+sp log <job-id>               # lean runtime/control/error log; from a parent dir aggregates child repo DBs
+sp log --specialist reviewer -f
 sp chat explorer --bead <id>    # launch interactive TUI; input auto-steers/resumes
 sp result <job-id> --wait
 sp steer <job-id> "focus only on X"

package/config/mandatory-rules/research-tool-routing.md

@@ -7,6 +7,10 @@ Pick the right source before invoking research. Default to the project knowledge
 - `find-docs` / context7 — library, framework, SDK, CLI, or cloud-service docs (API syntax, config, migration).
 - `deepwiki` — public GitHub repo internals (architecture, conventions, code paths).
 - `github-search` (ghgrep) — real-world code patterns and API usage examples.
+- `ddgs` — general web search, no API key (`ddgs text -q "<query>" -m 8`). Discover authoritative URLs for vendor docs, blogs, papers, or proprietary products the above don't cover.
+- `agent-browser` — read/interact with any URL, including JS-rendered pages (`agent-browser open <url>` → `get text body`; close with `agent-browser close --all`).
 - `last30days` — recent web/social signals (Reddit, X, HN, YouTube). Early-warning only, never authoritative.
 
+General web (not a library/repo/social topic): use `ddgs` to discover URLs, then `agent-browser` to read them. Never point `agent-browser` at a search engine — headless Chrome gets CAPTCHA-blocked; search with `ddgs` instead. If `ddgs`/`agent-browser` aren't installed, report the gap (`uv tool install ddgs`; `npm i -g agent-browser && agent-browser install`) rather than answering from memory.
+
 Invoke skills on demand, not by default. Cite the source for every external claim.

package/config/mandatory-rules/test-runner-execution-scope.md

@@ -2,4 +2,4 @@
 name: test-runner-execution-scope
 kind: mandatory-rule
 ---
-Run only requested tests. Report failures with root cause and fix hints; do not expand scope.
+Run only requested tests. Exact command input wins over manifest fallback. If fallback is used, label it clearly as fallback. Report failures with root cause, owner classification, and next-recipient hints; do not expand scope.

package/config/skills/specialists-creator/SKILL.md

@@ -575,7 +575,34 @@ Informational declarations used by pre-run validation and future tooling (e.g. `
 }
 ```
 
-Writes the final session output to this file path after the session completes. Relative to the working directory.
+When set, the specialist writes its **handoff block** to this file on every substantive turn — foreground and `--background`. The content is identical to what is appended to the input bead notes and shown by `sp result`: a markdown heading, the verbatim specialist output, and an italic metadata footer.
+
+- **No env flag required.** `output_file` is honored whenever it is set (since unitAI-f58ma). It does NOT require `SPECIALISTS_JOB_FILE_OUTPUT` — that flag now only gates the debug file-mirrors (events.jsonl / status.json / result.txt).
+- **Single writer.** In a supervised run (`sp run`) the supervisor owns the file and the runner's own write is suppressed, so the file is never double-written. (In script/serve runs there is no supervisor; the runner writes the raw output instead of the enveloped block.)
+- **Format is the rendered handoff block, not bare output.** A downstream specialist that consumes this file as input will see the header/footer envelope around the body.
+- **Append vs overwrite is controlled by `notes_mode`** (see below): `full-trail` appends each turn; `final-only` overwrites with just the final `[FINAL · DONE]` block.
+- **Gitignore the path** if you don't want it committed — specs with `output_file` always write, so add the path (e.g. `.specialists/*-result.md`) to `.gitignore`.
+
+Relative paths resolve from the working directory.
+
+### `specialist.notes_mode`
+
+Controls how per-turn handoff output is persisted to BOTH the input bead notes and `output_file`.
+
+| Value | Behavior |
+|---|---|
+| `"full-trail"` (default) | Append every substantive turn. Bead notes / `output_file` accumulate `### … [turn N · WAITING]` blocks, ending with a final `## … [FINAL · DONE]` block. Best for keep-alive specialists where the operator wants the full trail. |
+| `"final-only"` | Persist only the single canonical `## … [FINAL · DONE]` block; intermediate turns are skipped and `output_file` is OVERWRITTEN (not appended). Best for non-coding / chained pipelines where the next specialist reads the previous specialist's bead note or `output_file` as its input and only wants the final result. |
+
+Empty turns are never persisted. The handoff block is markdown-native (heading + verbatim body + one italic metadata footer); the model string is normalized (provider prefix stripped, e.g. `nano-gpt/moonshotai/kimi-k2.5` renders as `kimi-k2.5`).
+
+```json
+{ "notes_mode": "final-only" }
+```
+
+### Handoff / pipeline output recipe
+
+For a non-coding pipeline where each specialist reads the previous one's result, set `output_file` to a known path AND `notes_mode: "final-only"` so the file (and the bead note) holds exactly the final result, overwritten each run — clean for the next specialist to consume. For a human-monitored keep-alive specialist, leave `notes_mode: "full-trail"` (default) so the operator sees every turn accumulate. `output_file` needs no env flag; just gitignore its path.
 
 ### `specialist.validation` (optional)
 

package/config/skills/using-specialists-auto/SKILL.md

@@ -39,7 +39,7 @@ read bead → write 7-section contract (child impl bead) → bd dep add parent
   → sleep 10 && sp ps                              # confirm started, not stuck queued
   → sleep <role-typical from v3> & sp ps          # check (see v3 Monitoring section)
   → sp result <exec-job>                           # consume immediately on transition to waiting
-  → optional advisory passes per v3 (code-sanity if smelly, security-auditor if risk surface)
+  → optional advisory passes per v3 (seconder if smelly, security-auditor if risk surface)
   → write reviewer bead contract → sp run reviewer --bead <review> --job <exec-job> --background
   → sleep 90 & sp ps
   → sp result <reviewer-job>

package/config/skills/using-specialists-v2/SKILL.md

@@ -215,7 +215,7 @@ Run `specialists list` if you need the live registry. Choose by task, not by hab
 | Design/tradeoffs | `overthinker` | The approach is risky, ambiguous, or needs critique. |
 | Implementation | `executor` | The contract is clear enough to write code or docs. |
 | Compliance/code review | `reviewer` | An executor/debugger produced changes that need the final PASS/PARTIAL/FAIL verdict. |
-| Implementation sanity | `code-sanity` | You want a cheap READ_ONLY smell pass for simplicity, type safety, dead code, brittle async/error handling, or maintainability before reviewer. |
+| Implementation sanity | `seconder` | You want a cheap READ_ONLY smell pass for simplicity, type safety, dead code, brittle async/error handling, or maintainability before reviewer. |
 | Security/dependency audit | `security-auditor` | You need threat modeling, secure-code review, package advisory triage, or agent/config security scanning. LOW: scan/read/recommend only. |
 | Multiple review perspectives | `parallel-review` | A critical diff needs independent review passes. |
 | Test execution | `test-runner` | You need suites run and failures interpreted. |
@@ -247,7 +247,7 @@ specialists doctor --check-drift                 # inspect stale .specialists/de
 sp prune-stale-defaults --dry-run                # preview redundant default snapshots
 specialists run <name> --bead <id> --background
 specialists run executor --bead <impl-bead> --background       # worktree auto-provisioned
-specialists run code-sanity --bead <sanity-bead> --job <exec-job> --keep-alive --background
+specialists run seconder --bead <sanity-bead> --job <exec-job> --keep-alive --background
 specialists run security-auditor --bead <security-bead> --job <exec-job> --keep-alive --background
 specialists run reviewer --bead <review-bead> --job <exec-job> --keep-alive --background
 specialists ps
@@ -343,7 +343,7 @@ specialists run executor --worktree --bead <impl> --context-depth 3 --background
 specialists result <exec-job>
 ```
 
-Optional code-sanity pass for implementation smell checks (use when the diff is non-trivial or likely to accumulate agent-code complexity):
+Optional seconder pass for implementation smell checks (use when the diff is non-trivial or likely to accumulate agent-code complexity):
 
 ```bash
 bd create --title "Code sanity check token refresh retry" --type task --priority 3 \
@@ -355,11 +355,11 @@ CONSTRAINTS: At most 5 concrete findings; cite files/symbols/lines where possibl
 VALIDATION: Findings are suitable to paste into specialists resume <exec-job>.
 OUTPUT: OK/FINDINGS/BLOCKED with handoff."
 bd dep add <sanity> <impl>
-specialists run code-sanity --bead <sanity> --job <exec-job> --context-depth 3 --keep-alive --background
+specialists run seconder --bead <sanity> --job <exec-job> --context-depth 3 --keep-alive --background
 specialists result <sanity-job>
 ```
 
-If code-sanity returns `FINDINGS`, resume executor with those concrete instructions, then rerun code-sanity only if the fixes were substantive. Do not treat code-sanity `OK` as reviewer PASS.
+If seconder returns `FINDINGS`, resume executor with those concrete instructions, then rerun seconder only if the fixes were substantive. Do not treat seconder `OK` as reviewer PASS.
 
 Optional security pass when the task touches auth, secrets, input handling, dependency updates, package advisories, agent config, hooks, or exposed endpoints:
 
@@ -492,7 +492,7 @@ Standard loop:
 ```text
 executor --worktree --bead impl
   -> waiting after turn
-optional code-sanity --bead sanity --job exec-job
+optional seconder --bead sanity --job exec-job
   -> OK: continue
   -> FINDINGS: resume executor with exact sanity findings
 optional security-auditor --bead security --job exec-job
@@ -506,7 +506,7 @@ reviewer --bead review --job exec-job
 
 Prefer `sp resume <exec-job>` over a new fix executor when the original job is waiting and context is healthy. Use a new fix bead with `--job <exec-job>` only when the original executor is dead, context exhausted, or a separate audit trail is required.
 
-Code-sanity and security-auditor outputs are advisory inputs to the chain; reviewer output must still be consumed before publishing. Do not treat job completion, code-sanity OK, or security no-findings as equivalent to reviewer acceptance.
+Seconder and security-auditor outputs are advisory inputs to the chain; reviewer output must still be consumed before publishing. Do not treat job completion, seconder OK, or security no-findings as equivalent to reviewer acceptance.
 
 ## Dependency Mapping