evidence-band

1import { atom, read, update } from 'claude-code'
2import type { Register } from 'claude-code'
3
4import type { Evidence } from '../types'
5
6const evidence = atom({ plugin: 'evidence-band', key: 'evidence' } as const, {
7  isAudit: false,
8  code: [],
9  docs: [],
10} as Evidence)
11
12const AUDIT = /\b(status|audit|sprint|smells?|review|tracker|is .* (done|complete)|what'?s left)\b/i
13// ponytail: path heuristic; extend when a project keeps requirements elsewhere
14const DOC = /(^|\/)(docs?|adr|specs?|\.planning|\.driver-seat)\/|(^|\/)(README|CHANGELOG|ROADMAP|TODO|CLAUDE)[^/]*$|tracker|\.mdx?$/i
15const READ_CMD = /^\s*(cat|head|tail|sed|grep|rg|less|bat|wc)\b/
16const PATHISH = /^[\w.~\/-]+\.[\w]+$|\//
17
18const CITE = `# Evidence rule (enforced by a plugin)
19This prompt asks for status, an audit or a review. Before answering:
20- Read the project's docs (README, docs/, specs, tracker) AND the code they describe.
21- Every finding or status claim cites both: the doc section and the file:line.
22- Drop any finding a doc explicitly requires. Say plainly what you did not verify.`
23
24export function sort(paths: readonly string[], e: Evidence): Evidence {
25  const add = (list: string[], p: string) => (list.includes(p) ? list : [...list, p])
26  return paths.reduce(
27    (acc, p) => (DOC.test(p) ? { ...acc, docs: add(acc.docs, p) } : { ...acc, code: add(acc.code, p) }),
28    e,
29  )
30}
31
32export function bashPaths(command: string): string[] {
33  if (!READ_CMD.test(command)) return []
34  return command
35    .split(/[\s|;&]+/)
36    .slice(1)
37    .filter(t => !t.startsWith('-') && PATHISH.test(t))
38}
39
40export const register: Register = on => {
41  on('prompt.submit', async ($, e, next) => {
42    await update($, evidence, () => ({ isAudit: AUDIT.test(e.text), code: [], docs: [] }))
43    return next(e)
44  })
45
46  on('prompt.compose', async ($, e, next) => {
47    const composed = await next(e)
48    if (!(await read($, evidence)).isAudit) return composed
49    return {
50      sections: [...composed.sections, { id: 'evidence-band:cite', text: CITE, scope: 'session' as const }],
51    }
52  })
53
54  on('tool.call', { tool: 'Read' }, async ($, e, next) => {
55    await update($, evidence, ev => sort([e.file_path], ev))
56    return next(e)
57  })
58
59  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
60    const paths = bashPaths(e.command)
61    if (paths.length > 0) await update($, evidence, ev => sort(paths, ev))
62    return next(e)
63  })
64
65  on('turn.complete', async ($, e, next) => {
66    const ev = await read($, evidence)
67    if (ev.isAudit && (ev.docs.length === 0 || ev.code.length === 0)) {
68      $.ui.toast(`Audit answer without reading ${ev.docs.length === 0 ? 'docs' : 'code'}. Ask for evidence.`)
69    }
70    return next(e)
71  })
72
73  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
74    const ev = await read($, evidence)
75    if (!ev.isAudit || e.props.hasSurvey) return next(e)
76    const { Box, Text } = $.ui.resolve(e)
77    const mark = (n: number) => (n > 0 ? `✓${n}` : '✗')
78    return (
79      <Box flexDirection="column">
80        <Text dimColor>
81          evidence · code {mark(ev.code.length)} · docs {mark(ev.docs.length)}
82        </Text>
83        {await next(e)}
84      </Box>
85    )
86  })
87}
88

1export type Evidence = { isAudit: boolean; code: string[]; docs: string[] }
2
3declare module 'claude-code' {
4  interface PluginState {
5    'evidence-band': { evidence: Evidence }
6  }
7}
8