Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Claude Code mods (plugins with a hooks module), served as a local folder marketp

| mod | version | what it does |
| --- | --- | --- |
| [harness](harness/) | 0.3.4 | The integrated harness: the user's Claude rules enforced at the tool call, session tooling and workflow automation (formerly house-rules) |
| [harness](harness/) | 0.5.0 | The integrated harness: the user's Claude rules enforced at the tool call, session tooling and workflow automation (formerly house-rules) |
| [auto-claude](auto-claude/) | 1.4.0 | Unattended run of a repository through to live: plans the long-term goal, milestones and deploy; its own loop builds and judges each milestone in a worktree; ships each (push, PR, required CI, merge), deploys and smoke-checks it; a watchdog repairs or routes around stalls; replans until the final check passes. Absorbed goal-mode in 1.0.0; since 1.1.0 the session never rests: the next milestone is built, stacked, while a PR waits on CI; since 1.3.0 a line can wait on a training run or cache build (`:: after:`, `wait_until`) without ending the run; since 1.4.0 `--always-on` stands by after the final check and wakes for new cycles from Linear, the live smoke check, the default branch's CI and labelled GitHub issues |
| [model-tier](model-tier/) | 0.11.0 | Routes each main-loop turn to fable, opus, sonnet or haiku and a reasoning effort by task complexity, with a `set_tier` tool the model calls to correct either |
| [refactor](refactor/) | 0.1.3 | Enforces the architecture a repo declares in `.claude/architecture.json` at Edit/Write (layer direction, forbidden imports), notes code smells with the refactoring.guru technique to apply, `/arch audit` for violations and import cycles |
Expand Down
6 changes: 3 additions & 3 deletions auto-claude/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ With `--always-on` (or the `alwaysOn` option), a run does not end when its final
- **Trust.** Labelling needs triage access, so the label is the gate: an issue is work when someone who may label it says so, once. Only its number and title go into the line, with `::` and brackets removed, so a title cannot add a check or a base. The model reads the issue itself while building; its body is still third-party text, so label only issues whose body you would hand the run. Peer messages and webhook text do not wake a run.
- **`--once`** opts a single start out when `alwaysOn` is the default.
- **Waking.** Only when the session has had no turn for 2 min: a person may use the session while it stands by. A cycle builds, ships and deploys like any run, without a new planning round; its final check passing stands it by again. A failing one replans, as a run does.
- **Standing by owns nothing.** The guards and the unattended policy are off, `.claude/auto-claude.on` says `on: false, phase: standby` (harness's Linear rules apply again), and the watchdog's idle notices are quiet.
- **Standing by owns nothing.** The guards and the unattended policy are off, `.claude/auto-claude.on` says `on: false, phase: standby`, and the watchdog's idle notices are quiet.
- **Caps.** `maxMerges` and `maxHours` count per cycle; standby time counts toward neither. `maxMergesPerDay` (20) holds a wake back while the last 24 h hold that many merges, told once. 3 deploys failing in a row still stop the run.
- **Memory.** Each cycle adds one line under `## Cycles` in `auto-plan.md`: what woke it, what merged, was held and deployed. On entering standby the session is compacted once (when its context is 30% full or more), keeping the goal, decisions and cycles.
- **Quiet.** In standby a person is told only of a wake (and why), a cycle's end, a failing smoke check or GitHub poll, and the daily cap.
Expand Down Expand Up @@ -112,9 +112,9 @@ A run keeps the repository's Linear project in step, through the session's own `
- **Planning.** The planning prompt (and each replan) lists the project's open issues: triage, backlog, unstarted and started. A milestone that resolves issues starts with their IDs: `- [ ] [AX-12] <end state> :: check: <command>`. An open issue the plan leaves out gets a line under `## Decisions`.
- **While the run goes.** Every 10 minutes, and once more before the run may finish, the driver reads the open issues. It also reads the newest comments on the 25 most recently changed issues and on every issue the run has a line for. A new comment on an older issue waits until the issue itself changes. Every open issue counts as covered from the moment the run starts, so comments written before it never count. A run that started unmapped (or under an older version) adopts the project on its next tick. Comments do not move an issue's `updatedAt` (measured 2026-11-13), so they are read on their own. An issue that is new or changed since the run last covered it gets a queue line, at most 5 per sync. The line has no check, so the evaluator judges it: `- [ ] [AX-12] <title>: what Linear AX-12 asks is resolved on this branch (…)`. A change to an issue whose line is still pending is covered by that line. A change to an issue being built or shipped is looked at when it merges. Each issue gets at most 2 follow-up lines.
- **Closed issues.** An issue closed while its line waits (cancelled, done elsewhere) blocks that line. The driver never moves a closed issue back to `started`. At merge, a closed issue only gets the evidence comment.
- **No new issues during a run.** The model is told not to create issues, and harness refuses an unrequested create while a run owns the repository. Otherwise a new issue would become a milestone of the same run.
- **No new issues during a run.** The model is told not to create issues, and harness refuses an issue create the user did not ask for. Otherwise a new issue would become a milestone of the same run.
- **Write-back.** A milestone that starts moves its issues to `started`. One that merges moves them to `completed`, with a comment naming the PR. If the issue changed in Linear while the milestone was built, it stays open instead, with a comment and a follow-up line. A held or blocked milestone gets a comment only. The driver's comments start with `[auto-claude]` and never count as changes. The model is told never to change these issues' state or comment on them.
- **Signal for other mods.** Each tick writes `.claude/auto-claude.on` (`{ on, phase, at }`, git-excluded). harness reads it, and leaves issue states to the driver while a run owns the repository.
- **Signal for other mods.** Each tick writes `.claude/auto-claude.on` (`{ on, phase, at }`, git-excluded), so other mods can tell whether a run owns the repository.
- `--queue` runs neither read nor write Linear.

## Autonomy and its limits
Expand Down
7 changes: 3 additions & 4 deletions auto-claude/hooks/register.ts
Original file line number Diff line number Diff line change
Expand Up @@ -89,16 +89,15 @@ async function readRecord($: EngineInterface, root: string): Promise<AutoRecord

async function writeRecord($: EngineInterface, r: AutoRecord): Promise<void> {
await $.store.set(STORE(r.root), r)
// Other plugins cannot read this store: harness reads this file to know a run
// owns the repository (its Linear flow leaves issue states to the driver).
// Other plugins cannot read this store: this file tells them a run owns the
// repository.
// A run standing by owns nothing: the person may work in the repository meanwhile.
await $.fs.write(`${r.root}/.claude/auto-claude.on`, `${JSON.stringify({ on: owns(r), phase: r.phase, at: await $.clock.now() })}\n`).catch(() => undefined)
await show($, r)
}

// The run holds the session and the repository: on, and not standing by
// between cycles. Its guards, its unattended policy and harness's hands-off
// Linear flow apply only then.
// between cycles. Its guards and its unattended policy apply only then.
const owns = (r: Pick<AutoRecord, 'on' | 'phase'> | undefined): boolean => r?.on === true && r.phase !== 'standby'

// Issue IDs of queue lines not started yet, and of the milestones being built or shipped.
Expand Down
2 changes: 1 addition & 1 deletion harness/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "harness",
"version": "0.4.1",
"version": "0.5.0",
"description": "Integrated harness: the user's Claude rules enforced at the tool call (git, worktree, delete, venv, port, Linear, memory and order guards; a merge-and-release gate; report lint), plus session tooling and workflow automation.",
"author": {
"name": "unohee"
Expand Down
12 changes: 1 addition & 11 deletions harness/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ The user's own Claude harness as one mod (formerly `house-rules`). It covers thr
- session tooling that used to be shell hooks and prose commands;
- workflow automation for `/commit` and the heartbeat loop.

Each rule feature can be switched with `/harness on|off guards|ship-gate|report-lint|repo-size|linear-flow`. The choice is kept across sessions. `/harness status` shows the current state.
Each rule feature can be switched with `/harness on|off guards|ship-gate|report-lint|repo-size`. The choice is kept across sessions. `/harness status` shows the current state.

Design rule: a check that is deterministic and unambiguous **refuses**. A heuristic one only adds a **note** for the model, and is promoted once false positives have been measured.

Expand Down Expand Up @@ -47,16 +47,6 @@ Refuses or rewrites a single tool call.
- When an AskUserQuestion auto-continues unanswered, the model is told to take each question's `(Recommended)` option.
- If that option is irreversible, it takes the safe hold option instead.

## linear-flow (on)

Since 2026-11-13 an agent works under a Linear issue, and the issue ends Done. This replaces the "only on request" rule of CLAUDE.md §1.5 for creating issues and comments (cancel/split still need the user's approval).

- **Open first:** `Edit`, `Write`, `NotebookEdit`, `git commit`, `git push` and `gh pr create` are refused until the session has an issue: one it created (`save_issue` with no `id`) or an existing one it picked up (`save_issue` with an `id` and a started state: In Progress, In Review, `started`). A label or priority edit is not a pick-up. Editing under `~/.claude/`, `/tmp`, `$TMPDIR` or a `trash/` folder is not project work and is exempt. The refusal says how to search for duplicates, open the issue, and which team `~/.claude/linear.json` maps the repo to.
- **Done before stop:** the turn may not stop while an issue the session opened or picked up is not Done. A Cancel/Duplicate transition (which needs the user's approval) takes the issue off the list. The Stop is blocked up to twice (the ship-gate counter), then only a toast. An issue the user merely names is not tracked until the agent picks it up.
- **Issue ID:** read from the `id` field of the `save_issue` result (live shape, 2026-11-13); an `identifier` field is accepted too.
- **auto-claude runs:** while `<repo>/.claude/auto-claude.on` says a run is on and ticked within 15 minutes, nothing is gated and the Stop is not blocked: the auto-claude driver opens, moves and closes the issues itself. Creating an issue goes back to needing the user's request, since a new issue would become a milestone of that run.
- **Off:** `/harness off linear-flow` (kept across sessions) brings back the "only on request" behaviour. Do that when Linear is unavailable, or the refusal would deadlock the session.

## repo-size (on)

Keeps repos under `~/dev` within a size budget: 5 GB of the whole directory, `.git` and ignored files included. Measured on 2026-10-31, most overruns came from `worktrees/`, `trash/` and `testing/`, which the user's own rules produce. A few came from a `.git` full of loose objects.
Expand Down
2 changes: 1 addition & 1 deletion harness/hooks/ask-default.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import { DEFAULT_TOGGLES } from './state'

type On = Parameters<Register>[0]

const togglesAtom = atom({ plugin: 'harness', key: 'toggles' } as const, DEFAULT_TOGGLES, { shape: 'toggles-3' })
const togglesAtom = atom({ plugin: 'harness', key: 'toggles' } as const, DEFAULT_TOGGLES, { shape: 'toggles-4' })

export type AskQuestion = { question: string; options: ReadonlyArray<{ label: string }> }

Expand Down
88 changes: 11 additions & 77 deletions harness/hooks/flow.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,6 @@ type World = {
proc?: (argv: readonly string[]) => string | undefined
logs: string[]
// What a Linear save_issue (create) answers with.
created?: string
}

// The engine beneath the plugin: tools answer with what they were given, so a
Expand All @@ -29,9 +28,7 @@ function world(on: On, store: Record<string, unknown> = {}): World {
w.logs.push(String(e.text))
return { value: undefined }
})
// The Linear flow is opt-in per test: the older tests edit files with no issue open.
const stored = store.toggles as Record<string, unknown> | undefined
mock.store(on, { ...store, toggles: { linearFlow: false, ...stored } })
mock.store(on, store)
mock.env(on, { HOME: '/Users/u', TMPDIR: '/var/folders/xx/T/' })
on('command.register', (_, e) => ({ value: { command: e.name } }))
on('session.start', (_, e) => ({ cwd: e.cwd }))
Expand Down Expand Up @@ -66,7 +63,6 @@ function world(on: On, store: Record<string, unknown> = {}): World {
on('tool.call', (_, e) => {
const input = e as unknown as { command?: string }
w.ran.push(input.command ?? e.tool)
if (e.tool === 'mcp__linear-server__save_issue' && w.created !== undefined && !('id' in e)) return { result: w.created }
return { result: input.command ?? 'ok' }
})

Expand Down Expand Up @@ -410,7 +406,7 @@ describe('phase 3', () => {
})

test('session.start draws the normal status (no row) and session.end clears the piece by the ending id', async ($, on) => {
const w = world(on, { toggles: { linearFlow: true } })
const w = world(on)
on('session.id', () => ({ value: 'live' }))
on('session.end', (_, e) => ({ sessionId: e.sessionId }))
const statuses: unknown[] = []
Expand All @@ -436,84 +432,22 @@ describe('phase 3', () => {
})
})

describe('linear flow', () => {
const FLOW = { toggles: { linearFlow: true, reportLint: false } }
const save = ($: Engine, input: Record<string, unknown>) => $.tool.call({ tool: 'mcp__linear-server__save_issue', ...input })

test('a change is refused until an issue is opened, then allowed; paths outside the project are exempt', async ($, on) => {
const w = world(on, FLOW)
w.created = '[{"type":"text","text":"{\\"id\\":\\"QQQ-5\\",\\"title\\":\\"x\\"}"}]'
await start($)
await prompt($, '테스트 고쳐줘')
const refused = await $.tool.call({ tool: 'Write', file_path: '/repo/a.py', content: 'x\n' })
expect(refused.deny).toContain('Linear flow')
expect((await $.tool.call({ tool: 'Bash', command: 'git commit -m "x"' })).deny).toContain('Linear flow')
expect((await $.tool.call({ tool: 'Bash', command: 'ls' })).deny).toBeUndefined()
expect((await $.tool.call({ tool: 'Write', file_path: '/Users/u/.claude/projects/-x/memory/a.md', content: 'x\n' })).deny).toBeUndefined()
expect((await $.tool.call({ tool: 'Write', file_path: '/tmp/scratch.py', content: 'x\n' })).deny).toBeUndefined()

expect((await save($, { title: 'x', team: 'T' })).deny).toBeUndefined()
expect((await $.tool.call({ tool: 'Write', file_path: '/repo/a.py', content: 'x\n' })).deny).toBeUndefined()
expect(w.ran).toContain('ls')
})

test('an opened issue blocks the stop until it is Done', async ($, on) => {
world(on, FLOW).created = '{"identifier":"QQQ-5"}'
await start($)
await prompt($, '고쳐줘')
await save($, { title: 'x', team: 'T' })
await $.tool.call({ tool: 'Write', file_path: '/repo/a.py', content: 'x\n' })

const blocked = await $.classic.Stop(STOP)
expect(blocked.block).toContain('QQQ-5')
await save($, { id: 'QQQ-5', state: 'Done' })
expect((await $.classic.Stop(STOP)).block).toBeUndefined()
})

test('picking up an existing issue counts; after two blocks the stop passes with a toast', async ($, on) => {
const w = world(on, FLOW)
describe('linear-flow removed (0.5.0)', () => {
test('a stored linear-flow toggle is dropped: edits are not gated, a picked-up issue does not block the stop', async ($, on) => {
world(on, { toggles: { linearFlow: true, reportLint: false } })
await start($)
await prompt($, 'QQQ-7 진행해줘')
expect((await $.tool.call({ tool: 'Write', file_path: '/repo/a.py', content: 'x\n' })).deny).toContain('Linear flow')
await save($, { id: 'QQQ-7', state: 'In Progress' })
expect((await $.tool.call({ tool: 'Write', file_path: '/repo/a.py', content: 'x\n' })).deny).toBeUndefined()

expect((await $.classic.Stop(STOP)).block).toContain('QQQ-7')
expect((await $.classic.Stop(STOP)).block).toContain('QQQ-7')
expect((await $.classic.Stop(STOP)).block).toBeUndefined()
expect(w.toasts.join(' ')).toContain('QQQ-7')
})

test('off: nothing is required; subagent stops are left alone', async ($, on) => {
world(on, FLOW)
await start($)
await command($, 'off linear-flow')
await prompt($, '고쳐줘')
expect((await $.tool.call({ tool: 'Write', file_path: '/repo/a.py', content: 'x\n' })).deny).toBeUndefined()
expect((await $.tool.call({ tool: 'Bash', command: 'git commit -m "x"' })).deny).toBeUndefined()
expect((await $.tool.call({ tool: 'mcp__linear-server__save_issue', id: 'QQQ-7', state: 'In Progress' })).deny).toBeUndefined()
expect((await $.classic.Stop(STOP)).block).toBeUndefined()
expect((await command($, 'status')).text).not.toContain('linear-flow')
})

test('a label edit is not a claim; a cancelled issue is not demanded Done', async ($, on) => {
world(on, FLOW)
await start($)
await prompt($, 'QQQ-8 정리해줘')
await save($, { id: 'QQQ-8', priority: 2 })
expect((await $.tool.call({ tool: 'Write', file_path: '/repo/a.py', content: 'x\n' })).deny).toContain('Linear flow')
await save($, { id: 'QQQ-8', state: 'In Progress' })
await $.tool.call({ tool: 'AskUserQuestion', questions: [] })
await save($, { id: 'QQQ-8', state: 'Canceled' })
expect((await $.classic.Stop(STOP)).block).toBeUndefined()
})

test('while an auto-claude run owns the repo, nothing is gated or blocked', async ($, on) => {
const w = world(on, FLOW)
w.files.set('/repo/.claude/auto-claude.on', JSON.stringify({ on: true, phase: 'run', at: Date.now() }))
test('creating an issue needs a Linear request again', async ($, on) => {
world(on)
await start($)
await prompt($, '[auto-claude loop] Milestone #1')
expect((await $.tool.call({ tool: 'Write', file_path: '/repo/worktrees/goal-01/a.py', content: 'x\n' })).deny).toBeUndefined()
expect((await $.tool.call({ tool: 'Bash', command: 'git commit -m "m1"' })).deny).toBeUndefined()
await prompt($, '테스트 고쳐줘')
expect((await $.tool.call({ tool: 'mcp__linear-server__save_issue', title: 'x', team: 'T' })).deny).toContain('§1.5')
w.files.set('/repo/.claude/auto-claude.on', JSON.stringify({ on: false, phase: 'done', at: Date.now() }))
expect((await $.tool.call({ tool: 'Write', file_path: '/repo/a.py', content: 'x\n' })).deny).toContain('Linear flow')
})
})
4 changes: 2 additions & 2 deletions harness/hooks/guards.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ import { DEFAULT_TOGGLES, INITIAL_LINT, INITIAL_SHIP } from './state'
import type { ToolCallHook } from './state'

const envAtom = atom({ plugin: 'harness', key: 'env' } as const, {}, { shape: 'env-1' })
const togglesAtom = atom({ plugin: 'harness', key: 'toggles' } as const, DEFAULT_TOGGLES, { shape: 'toggles-3' })
const togglesAtom = atom({ plugin: 'harness', key: 'toggles' } as const, DEFAULT_TOGGLES, { shape: 'toggles-4' })
const lintAtom = atom({ plugin: 'harness', key: 'lint' } as const, INITIAL_LINT, { shape: 'lint-1' })
const shipAtom = atom({ plugin: 'harness', key: 'ship' } as const, INITIAL_SHIP, { shape: 'ship-3' })
const shipAtom = atom({ plugin: 'harness', key: 'ship' } as const, INITIAL_SHIP, { shape: 'ship-4' })
// The venv note was given in this session: once is enough (it rode every
// Python call, measured 2026-10-29, saying the same thing each time).
const venvNotedAtom = atom({ plugin: 'harness', key: 'venvNoted' } as const, false, { shape: 'venv-noted-1' })
Expand Down
Loading
Loading