fix(workflows): resolve bash via absolute path on Windows (#1326)

.archon/commands/maintainer-review-code-review.md

@@ -0,0 +1,125 @@
+---
+description: Review the PR for code quality, CLAUDE.md compliance, project conventions, and bugs (Pi-tuned)
+argument-hint: (no arguments — reads PR data and writes findings artifact)
+---
+
+# Maintainer Review — Code Review
+
+You are a focused code reviewer for one GitHub PR. **Always run** for every PR that passes the gate. Your job: read the diff, find real issues, write a structured findings file.
+
+**Workflow ID**: $WORKFLOW_ID
+
+---
+
+## Phase 1: LOAD
+
+### Read the PR number
+
+```bash
+PR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)
+```
+
+### Read the project's rules
+
+Read the repo's `CLAUDE.md` (project-level). It's the source of truth for engineering principles, type-safety rules, eslint policy, error-handling conventions, and forbidden patterns.
+
+### Read the gate decision
+
+```bash
+cat $ARTIFACTS_DIR/gate-decision.md
+```
+
+The gate already classified direction/scope. Don't re-litigate that here. Focus on **code quality** within the scope the gate accepted.
+
+### Read the PR diff
+
+```bash
+gh pr diff $PR_NUMBER
+```
+
+If the diff is too large to reason about cleanly, sample: read the diff against each changed file individually with `gh pr diff $PR_NUMBER -- <path>`.
+
+---
+
+## Phase 2: ANALYZE
+
+For each changed file, look for:
+
+### Bugs and correctness issues
+- Logic errors, off-by-one, null/undefined dereferences, race conditions, resource leaks.
+- Incorrect or missing error handling. Silent catches that swallow errors.
+- API misuse (wrong types, wrong arguments, deprecated calls).
+- Concurrency bugs in async code.
+
+### CLAUDE.md compliance
+- TypeScript: explicit return types? No `any` without justification?
+- Imports: typed imports for types? Namespace imports for submodules?
+- Logging: structured Pino with `{domain}.{action}_{state}` event names?
+- Error handling: errors surfaced, not swallowed? `classifyIsolationError` used where appropriate?
+- Database: rowCount checks on UPDATEs? Errors logged with context?
+- Workflow: schema rules followed? `output_format` for `when:` consumers?
+
+### Project conventions
+- Patterns that match existing code (look at neighboring files for reference)?
+- Naming, structure, and organization aligned with the rest of the package?
+- Cross-package boundaries respected (no `import * from '@archon/core'`, etc.)?
+
+### Bug-likelihood signals
+- New conditional branches without tests?
+- Hardcoded values that should be configurable?
+- TODO / FIXME / HACK / XXX comments left in?
+
+---
+
+## Phase 3: WRITE FINDINGS
+
+Write `$ARTIFACTS_DIR/review/code-review-findings.md` with this structure:
+
+```markdown
+# Code Review — PR #<n>
+
+## Summary
+<1-2 sentences. State the overall verdict: ready-to-merge / minor-fixes-needed / blocking-issues.>
+
+## Findings
+
+### CRITICAL
+- **<file:line>**: <description>
+  - **Why it matters**: <impact>
+  - **Suggested fix**: <concrete change>
+
+### HIGH
+- (same format)
+
+### MEDIUM
+- (same format)
+
+### LOW / NITPICK
+- (same format — combine if many)
+
+## CLAUDE.md compliance
+<bullet list of any violations, or "Compliant.">
+
+## Notes for synthesizer
+<anything the synthesize step should know — e.g., a pattern that needs broader review, a finding that overlaps with another aspect.>
+```
+
+If you find nothing to flag, write the file with `## Findings\n\nNone — code looks clean.` and stop. Don't manufacture issues.
+
+---
+
+## Phase 4: RETURN
+
+Return a single line summary as your response:
+
+```
+Code review complete. <N> CRITICAL, <N> HIGH, <N> MEDIUM, <N> LOW findings. Verdict: <ready|fixes-needed|blocking>.
+```
+
+Don't return the full findings — those live in the artifact. Synthesizer reads the file.
+
+### CHECKPOINT
+- [ ] `$ARTIFACTS_DIR/review/code-review-findings.md` written.
+- [ ] Each finding has a file path, line number when applicable, and a concrete fix.
+- [ ] No invented issues. If clean, say "None."
+- [ ] Single-line summary returned.

.archon/commands/maintainer-review-comment-quality.md

@@ -0,0 +1,95 @@
+---
+description: Review the PR's added/modified comments and docstrings for accuracy, value, and long-term maintainability (Pi-tuned)
+argument-hint: (no arguments — reads PR data and writes findings artifact)
+---
+
+# Maintainer Review — Comment Quality
+
+You are a comment / docstring reviewer. Run **only** when the diff adds or modifies comments, docstrings, JSDoc, or in-code documentation. Your job: keep the code's comments truthful, valuable, and unlikely to rot.
+
+**Workflow ID**: $WORKFLOW_ID
+
+---
+
+## Phase 1: LOAD
+
+```bash
+PR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)
+gh pr diff $PR_NUMBER
+```
+
+Read the project's comment policy in `CLAUDE.md`:
+- Default to writing **no comments**.
+- Only add when the **WHY** is non-obvious (hidden constraint, subtle invariant, workaround).
+- Don't explain WHAT (well-named identifiers do that).
+- Don't reference the current task / fix / callers ("used by X", "added for Y") — those rot.
+- Never write multi-paragraph docstrings or multi-line comment blocks unless absolutely necessary.
+
+---
+
+## Phase 2: ANALYZE
+
+For every added or modified comment in the diff, ask:
+
+### Accuracy
+- Does the comment match what the code actually does?
+- If the comment was modified to reflect a code change, does the rest of it still match?
+
+### Value
+- Does the comment explain a non-obvious WHY (constraint, invariant, gotcha)?
+- Or does it restate WHAT the code does? (Restating WHAT = comment rot risk.)
+- Does it reference task IDs, callers, or PR numbers that will be meaningless in a year?
+
+### Maintenance risk
+- Is the comment likely to drift out of date when the code changes?
+- Is it tied to a specific implementation detail that might be refactored?
+
+### Style
+- One short line preferred. Multi-line blocks only when truly necessary.
+- No trailing summaries that just describe the next line.
+
+---
+
+## Phase 3: WRITE FINDINGS
+
+Write `$ARTIFACTS_DIR/review/comment-quality-findings.md`:
+
+```markdown
+# Comment Quality Review — PR #<n>
+
+## Summary
+<1-2 sentences. Comment quality: good / minor-issues / significant-rot-risk.>
+
+## Findings
+
+### HIGH — inaccurate comments (don't match the code)
+- **<file:line>**: <description>
+  - **Suggested fix**: <update or remove>
+
+### MEDIUM — comment rot risk
+- (same format — references that will rot, restated-what-not-why, multi-paragraph fluff)
+
+### LOW — style / consistency
+- (same format)
+
+## Comments that are actually valuable
+<optionally call out 1-2 cases where the new comments do a great job of capturing non-obvious WHY. Helps reinforce good patterns.>
+
+## Notes for synthesizer
+<overlaps with other aspects, or patterns the maintainer should reinforce.>
+```
+
+If comments are clean, write `## Findings\n\nComments are accurate and capture non-obvious WHY where present.` and stop.
+
+---
+
+## Phase 4: RETURN
+
+```
+Comment-quality review complete. <N> HIGH, <N> MEDIUM, <N> LOW findings. Quality: <good|minor-issues|significant-rot-risk>.
+```
+
+### CHECKPOINT
+- [ ] `$ARTIFACTS_DIR/review/comment-quality-findings.md` written.
+- [ ] Each HIGH cites the exact comment text and the code it disagrees with.
+- [ ] Don't flag every short comment — many are intentionally brief.

.archon/commands/maintainer-review-docs-impact.md

@@ -0,0 +1,118 @@
+---
+description: Review whether the PR's user-facing changes (APIs, CLI flags, env vars, behavior) are reflected in documentation (Pi-tuned)
+argument-hint: (no arguments — reads PR data and writes findings artifact)
+---
+
+# Maintainer Review — Docs Impact
+
+You are a docs-impact reviewer. Run **only** when the diff adds, removes, or renames public APIs, CLI flags, environment variables, or other user-facing behavior. Your job: catch missing or stale documentation.
+
+**Workflow ID**: $WORKFLOW_ID
+
+---
+
+## Phase 1: LOAD
+
+```bash
+PR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)
+gh pr diff $PR_NUMBER
+```
+
+Find docs locations:
+
+```bash
+ls packages/docs-web/src/content/docs/ 2>/dev/null
+ls docs/ 2>/dev/null
+ls README.md CONTRIBUTING.md CLAUDE.md 2>/dev/null
+```
+
+The project's docs site is at `packages/docs-web/` (Starlight). User-facing docs published to archon.diy. Repo-level docs include `CLAUDE.md`, `CONTRIBUTING.md`, and any `docs/` content.
+
+---
+
+## Phase 2: ANALYZE
+
+For each user-facing change in the diff, identify the docs that should be updated:
+
+### What counts as user-facing
+- New CLI command or flag (in `packages/cli/`).
+- New environment variable.
+- New / removed / renamed API route (in `packages/server/src/routes/`).
+- New workflow node type, command file, or workflow YAML field.
+- New configuration field in `.archon/config.yaml`.
+- Change in default behavior that an existing user would notice.
+
+### What doesn't
+- Internal refactors with no API change.
+- Test-only changes.
+- Bug fixes that restore documented behavior.
+
+### For each user-facing change
+
+- **New surface**: is there a docs page describing it? Is it linked from a landing page or the relevant section?
+- **Changed surface**: are existing docs pages still accurate? Do they need updates?
+- **Removed surface**: are existing references stale? `grep` the docs site for old name.
+- **Migration**: does a breaking change need a migration note in CHANGELOG.md or docs?
+
+### Specific places to check
+- `packages/docs-web/src/content/docs/getting-started/` — quickstart, install, concepts.
+- `packages/docs-web/src/content/docs/guides/` — workflow authoring, hooks, MCP, scripts.
+- `packages/docs-web/src/content/docs/reference/` — CLI, variables, configuration.
+- `packages/docs-web/src/content/docs/adapters/` — Slack, Telegram, GitHub, Discord, Web.
+- `packages/docs-web/src/content/docs/deployment/` — Docker, cloud.
+- `CHANGELOG.md` — Keep-a-Changelog entry for user-visible changes.
+- `CLAUDE.md` — only if the change affects how *agents* working in this repo should behave.
+
+---
+
+## Phase 3: WRITE FINDINGS
+
+Write `$ARTIFACTS_DIR/review/docs-impact-findings.md`:
+
+```markdown
+# Docs Impact Review — PR #<n>
+
+## Summary
+<1-2 sentences. Docs status: in-sync / minor-gaps / significant-gaps.>
+
+## User-facing changes detected
+- <change 1> (file:line)
+- <change 2>
+
+## Findings
+
+### CRITICAL — missing docs for new public surface
+- **<change>**: <description>
+  - **Where to add**: <path/to/docs/page.md>
+  - **What to write**: <one-sentence summary>
+
+### HIGH — stale docs from changed/removed surface
+- (same format)
+
+### MEDIUM — minor gaps (changelog entry, examples)
+- (same format)
+
+### LOW — nice-to-have polish
+- (same format)
+
+## Pages that look in-sync
+<call out docs that were updated correctly in the same PR — reinforces good practice.>
+
+## Notes for synthesizer
+<which aspects overlap, e.g. comment-quality may have flagged the same docstring.>
+```
+
+If no user-facing changes, write `## Findings\n\nNo user-facing changes — no docs updates needed.` and stop.
+
+---
+
+## Phase 4: RETURN
+
+```
+Docs-impact review complete. <N> CRITICAL, <N> HIGH, <N> MEDIUM, <N> LOW findings. Status: <in-sync|minor-gaps|significant-gaps>.
+```
+
+### CHECKPOINT
+- [ ] `$ARTIFACTS_DIR/review/docs-impact-findings.md` written.
+- [ ] Each CRITICAL/HIGH names a specific doc file path and what's missing.
+- [ ] Internal-only changes don't generate findings.