Phase 21: polish write-mode smoke docs + guardrail UX

.github/workflows/ci.yml

@@ -17,4 +17,3 @@ jobs:
       - run: bun install
       - run: bun test
       - run: bunx tsc --noEmit
-        continue-on-error: true

.planning/STATE.md

@@ -9,16 +9,16 @@ See: .planning/PROJECT.md (updated 2026-02-09)
 
 ## Current Position
 
-**Current Phase:** 20
-**Current Phase Name:** next-improvements
-**Total Phases:** 20
-**Current Plan:** 1
-**Total Plans in Phase:** 1
-**Status:** Complete
-**Progress:** [██████████] 100%
+**Current Phase:** 21
+**Current Phase Name:** polish
+**Total Phases:** 21
+**Current Plan:** 2
+**Total Plans in Phase:** 4
+**Status:** In progress
+**Progress:** [#######   ] 75%
 
 **Last Activity:** 2026-02-10
-**Last Activity Description:** Phase 20 plan 01 complete; write-mode UX + guardrails + CI
+**Last Activity Description:** Phase 21: wrote xbmc/xbmc write-flow smoke doc; improved write guardrail refusal details; manual smoke run pending
 **Paused At:** None
 
 Milestone: v0.2 (planning)

.planning/phases/21-polish/21-01-PLAN.md

@@ -0,0 +1,76 @@
+---
+phase: 21-polish
+plan: 01
+type: execute
+wave: 1
+depends_on:
+  - 20-next-improvements/20-01-SUMMARY.md
+files_modified:
+  - .github/workflows/ci.yml
+  - src/lib/sanitizer.test.ts
+  - src/handlers/mention.ts
+  - src/handlers/review.ts
+  - docs/runbooks/mentions.md
+autonomous: true
+---
+
+<objective>
+Finish remaining polish items: make CI typecheck blocking, tighten guardrails refusal UX, add a non-chatty rereview trigger, and do a smoke test on xbmc repos.
+</objective>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Make CI typecheck blocking</name>
+  <files>.github/workflows/ci.yml src/lib/sanitizer.test.ts</files>
+  <action>
+  Fix TypeScript strictness errors so `bunx tsc --noEmit` can be required in CI.
+  Remove continue-on-error for the typecheck step.
+  </action>
+  <verify>
+  - bunx tsc --noEmit
+  - bun test
+  </verify>
+</task>
+
+<task type="auto">
+  <name>Task 2: Improve guardrail refusal UX</name>
+  <files>src/handlers/mention.ts docs/runbooks/mentions.md</files>
+  <action>
+  When write-mode is blocked (denyPaths/allowPaths/secret scan), reply with a concise reason including:
+  - policy code
+  - path involved (when available)
+  - next action (narrow allowPaths or adjust denyPaths)
+  </action>
+</task>
+
+<task type="auto">
+  <name>Task 3: Add non-chatty rereview trigger</name>
+  <files>src/handlers/mention.ts src/handlers/review.ts</files>
+  <action>
+  Keep `@kodiai review` working, but reduce/no-op the bot reply text when the review output is posted in the PR timeline.
+  </action>
+</task>
+
+<task type="auto">
+  <name>Task 4: Smoke test write-mode paths</name>
+  <files>docs/runbooks/mentions.md</files>
+  <action>
+  Run a smoke test on:
+  - same-repo PR (updates branch)
+  - fork PR (bot PR fallback)
+  - guardrail block (denyPaths/secret scan)
+  Document the steps.
+  </action>
+</task>
+
+</tasks>
+
+<verification>
+- bun test
+- bunx tsc --noEmit
+</verification>
+
+<output>
+Create `.planning/phases/21-polish/21-01-SUMMARY.md`.
+</output>

.planning/phases/21-polish/21-01-SUMMARY.md

@@ -0,0 +1,39 @@
+---
+phase: 21-polish
+plan: 01
+subsystem: mentions
+tags: [ci, mentions, rereview, polish]
+
+# Dependency graph
+requires:
+  - phase: 20-next-improvements
+    provides: write-mode UX/guardrails and CI baseline
+provides:
+  - CI typecheck is required (no continue-on-error)
+  - Minimal rereview mention commands (`@kodiai review` / `@kodiai recheck`)
+  - Guardrail refusals include a stable reason code
+affects: [ci, mentions]
+
+# Metrics
+duration: 15 min
+completed: 2026-02-10
+---
+
+# Phase 21 Plan 01: Polish Summary
+
+Focused polish pass to make CI stricter and make rereview interactions less chatty.
+
+- CI now requires `bunx tsc --noEmit` (typecheck is no longer best-effort).
+- Mention handler supports a minimal rereview command (`@kodiai review` / `@kodiai recheck`) intended to trigger the same review output without extra commentary.
+- When write-mode is blocked by policy (allow/deny paths, secret scan, rate limiting), refusals include a stable reason code to make troubleshooting and runbooks easier.
+
+## Verification
+
+- `bunx tsc --noEmit`
+- `bun test`
+
+## Task Commits
+
+1. `f563ef8ded` docs(21-polish-01): add plan and advance state
+2. `5fb5374d51` chore(ci): make typecheck required
+3. `0c67171594` feat(mention): add minimal rereview command

.planning/phases/21-polish/21-02-PLAN.md

@@ -0,0 +1,74 @@
+---
+phase: 21-polish
+plan: 02
+type: execute
+wave: 1
+depends_on:
+  - 21-polish/21-01-SUMMARY.md
+files_modified:
+  - docs/runbooks/mentions.md
+  - docs/smoke/xbmc-xbmc-write-flow.md
+autonomous: false
+---
+
+<objective>
+Run a real-world smoke test of the end-to-end write flow against xbmc/xbmc and document the exact steps and expected outputs, including how to grep evidence bundle logs by deliveryId.
+</objective>
+
+<tasks>
+
+<task type="manual">
+  <name>Task 1: same-repo PR write-mode updates PR branch</name>
+  <files>docs/smoke/xbmc-xbmc-write-flow.md</files>
+  <action>
+  Use `plan:` then `apply:` on a tiny, safe change in a PR whose head branch is in the base repo.
+  Confirm the bot updates the existing PR branch (no bot PR fallback).
+  Capture:
+  - PR URL
+  - trigger comment URL
+  - resulting commit/branch update evidence
+  - evidence bundle log fields, keyed by deliveryId
+  </action>
+</task>
+
+<task type="manual">
+  <name>Task 2: fork PR write-mode falls back to bot PR</name>
+  <files>docs/smoke/xbmc-xbmc-write-flow.md</files>
+  <action>
+  Use `plan:` then `apply:` on a tiny, safe change in a fork PR.
+  Confirm the handler cannot push to fork head and uses bot PR fallback.
+  Capture PR URLs (source + bot PR) and the evidence bundle log outcome.
+  </action>
+</task>
+
+<task type="manual">
+  <name>Task 3: guardrails block denied paths and secret-like content</name>
+  <files>docs/smoke/xbmc-xbmc-write-flow.md</files>
+  <action>
+  Attempt writes that should be refused:
+  - denied path (e.g. under `.github/`)
+  - secret-like content that triggers regex/entropy detection
+  Confirm the refusal message reports:
+  - rule
+  - file/path
+  - suggested smallest safe config change (or states none is safe)
+  </action>
+</task>
+
+<task type="auto">
+  <name>Task 4: document evidence bundle grepping by deliveryId</name>
+  <files>docs/runbooks/mentions.md</files>
+  <action>
+  Add a short section showing how to use the GitHub App delivery UI to obtain `X-GitHub-Delivery` and how to grep/query logs for the evidence bundle line.
+  </action>
+</task>
+
+</tasks>
+
+<verification>
+Manual verification per the smoke test doc. No code changes required.
+</verification>
+
+<output>
+Create `.planning/phases/21-polish/21-02-SUMMARY.md`.
+</output>

.planning/phases/21-polish/21-02-SUMMARY.md

@@ -0,0 +1,39 @@
+---
+phase: 21-polish
+plan: 02
+subsystem: write-mode
+tags: [smoke-test, docs, ops]
+
+# Dependency graph
+requires:
+  - phase: 21-polish
+    provides: baseline polish changes (CI strictness + rereview command)
+provides:
+  - Documented end-to-end smoke procedure for xbmc/xbmc write-mode
+  - Runbook snippet for grepping evidence bundle logs by deliveryId
+affects: [docs, ops]
+
+# Metrics
+duration: 10 min
+completed: 2026-02-10
+---
+
+# Phase 21 Plan 02: xbmc/xbmc Write-Flow Smoke Test Summary
+
+Prepared a concrete, real-world smoke test procedure for xbmc/xbmc covering the full write flow, plus a runbook snippet showing how to locate evidence bundle logs by `deliveryId`.
+
+## What Changed
+
+- Added an end-to-end smoke test checklist and expected outcomes:
+  - `docs/smoke/xbmc-xbmc-write-flow.md`
+- Added a short section to the mentions runbook on grepping evidence bundle logs by `deliveryId`:
+  - `docs/runbooks/mentions.md`
+
+## Manual Verification (Pending)
+
+Run the steps in `docs/smoke/xbmc-xbmc-write-flow.md` and record:
+
+- Same-repo PR: `outcome=updated-pr-branch`
+- Fork PR: `outcome=created-pr` (or `reused-pr` on rerun)
+- Guardrails: refusal includes rule + file/path + detector when applicable
+- Logs: evidence bundle line is easy to locate by `deliveryId`

.planning/phases/21-polish/21-03-PLAN.md

@@ -0,0 +1,51 @@
+---
+phase: 21-polish
+plan: 03
+type: execute
+wave: 1
+depends_on:
+  - 21-polish/21-01-SUMMARY.md
+files_modified:
+  - src/handlers/mention.ts
+  - src/handlers/mention.test.ts
+autonomous: true
+---
+
+<objective>
+Improve write guardrail refusal UX: include the triggering file/path, the triggering rule, and the smallest config change to allow it when safe.
+</objective>
+
+<notes>
+This plan also covers policy refusals on the PR-branch update path (same-repo PR head), not just bot PR creation.
+</notes>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: enrich refusal payload</name>
+  <files>src/handlers/mention.ts</files>
+  <action>
+  When a write is blocked by denyPaths, allowPaths mismatch, entropy scan, or regex secret detection:
+  - include `path` (or best-effort location) in the reply when available
+  - include a stable rule identifier (existing reason code)
+  - include a suggested minimal config change when safe (e.g. add a narrow allowPaths pattern), otherwise explicitly say no safe suggestion
+  </action>
+</task>
+
+<task type="auto">
+  <name>Task 2: add tests covering refusal message fields</name>
+  <files>src/handlers/mention.test.ts</files>
+  <action>
+  Add unit tests asserting the refusal reply includes rule + path and that suggestions are conservative.
+  </action>
+</task>
+
+</tasks>
+
+<verification>
+- bun test
+</verification>
+
+<output>
+Create `.planning/phases/21-polish/21-03-SUMMARY.md`.
+</output>

.planning/phases/21-polish/21-03-SUMMARY.md

@@ -0,0 +1,49 @@
+---
+phase: 21-polish
+plan: 03
+subsystem: write-mode
+tags: [guardrails, mentions, write-mode]
+
+# Dependency graph
+requires:
+  - phase: 21-polish
+    provides: write-mode guardrails baseline
+provides:
+  - Write-policy refusals include rule family + file/path + detector/pattern when available
+  - Same behavior for PR-branch update path (no bot-PR fallback on policy refusal)
+affects: [mentions, write-mode]
+
+# Metrics
+duration: 20 min
+completed: 2026-02-10
+---
+
+# Phase 21 Plan 03: Guardrails Refusal UX Summary
+
+Improved write-mode refusal UX to make it obvious what triggered a block and what the smallest safe config adjustment is (when applicable).
+
+## What Changed
+
+- Write-policy errors now carry structured context (best-effort):
+  - rule family (`denyPaths` / `allowPaths` / `secretScan`)
+  - file/path
+  - matched pattern (for glob rules)
+  - detector (for secretScan)
+- Mention handler formats refusals to include:
+  - `Reason` (stable code)
+  - `Rule`
+  - `File`
+  - `Matched pattern` / `Detector` when present
+  - Smallest allowPaths snippet when blocked by allowlist
+  - Conservative guidance for denyPaths + secretScan blocks
+
+Files changed:
+
+- `src/jobs/workspace.ts`
+- `src/handlers/mention.ts`
+- `src/handlers/mention.test.ts`
+
+## Verification
+
+- `bun test`
+- `bunx tsc --noEmit`