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
15 changes: 7 additions & 8 deletions .claude/skills/neutral-mayor/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -252,13 +252,11 @@ Then:
delivered for the next human or fix attempt to read, no more.
- **Explicit instruction to steer a loop** ("tell the hypaware loop to …") →
inject the human's text verbatim into that loop's pane with the LLP 0034
discipline: `tmux send-keys -t '=neutral-<name>:' C-u` first (the trailing
colon matters — send-keys takes a pane target, and a bare `=name` fails on
tmux 3.3a; it also clears any harness
prefill — never press Enter on text you did not type), then the message, then
Enter; verify within ~30 s that it left the input box (one extra Enter if
swallowed). Confirm in the thread once submission is verified. You steer only
on a human request; healing on your own judgment is the watchdog's job
discipline: write the literal message to a file you own, then run
`neutral safety send --session neutral-<name> --message-file <file>`.
The controller clears prefill, pastes without interpreting shell syntax,
and verifies submission. Confirm in the thread only when `submitted` is
true. You steer only on a human request; healing on your own judgment is the watchdog's job
(LLP 0041 §report-relay).
- **An ask to raise a PR's review budget** ("give hypaware#12 two more review
rounds") → author a comment on that PR — the rare authored case (LLP 0042):
Expand All @@ -271,7 +269,8 @@ Then:
unmarked relay above *is* the grant, since human comments grant directly.)
- **A question** → answer from ground truth re-derived *now* — `neutral prs
--json` / `neutral backlog --json` / `neutral issues --json` in the clones,
`gh`, transcripts, `tmux capture-pane` — never from memory of a past tick.
`gh`, transcripts, `neutral safety capture --session <session>` — never from
memory of a past tick.
If the question asks **how or why Neutral works** — its pipeline, reconciler
roles, artifacts, state transitions, scheduling, admission, review rungs,
authority boundaries, or why an artifact is in a state — call the Skill tool
Expand Down
83 changes: 55 additions & 28 deletions .claude/skills/neutral-reconcile/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,10 @@ work, the tick verifies it.
least-recently-run one past its cooldown and not damped, LLP 0047) — run that
member's initiative (code cleanup, below), then **return** and let the loop
schedule the next tick.
For `"pr-backlog"`, read and follow
[PR backlog autophagy](references/pr-backlog-autophagy.md) (LLP 0079).
Its no-op hint is `--backlog-snapshot <fingerprint>` on subsequent idle
calls, separate from the target-HEAD-based `--damped` members.
- `null` — **return**; the loop schedules the next tick (`ScheduleWakeup`). This
is a legitimate, common outcome: every member may be off, cooling down since a
recent PR disposition, or no-op damped. A deliberately idle tick is correct, not
Expand All @@ -139,21 +143,26 @@ action.

Include this completion contract in every dispatched worker prompt:

> Await background agents through the harness completion notification or
> `TaskOutput` with the task ID and `block: true, timeout: 600000`. Finish
> independent work first. For a CLI reviewer, run
> After starting a background agent or forked skill, finish independent work,
> then end your turn and await its completion notification. If `TaskOutput`
> is available, use the returned task ID with `block: true, timeout: 600000`.
> If tool discovery says it is unavailable, use the notification path. Keep
> the review incomplete until its actual result arrives; transcript silence
> and file timestamps are not completion. For a CLI reviewer, run
> `neutral run-worker --timeout-ms 1800000 -- <reviewer-command> <args...>`
> once using Bash background execution; await that task's completion. The
> runner buffers bounded output and returns the real exit status or timeout.
> Preserve full review artifacts on disk. A timeout or failed reviewer leaves
> the review incomplete; return the failure without a clean marker. For
> external CI, return and let the next reconcile tick observe it.

The container installs a shared tool hook that forces blocking `TaskOutput`
waits and rejects standalone waiting echoes. It applies to review children as
well as the coordinator. The runner owns the process timeout; the model does
not poll it. A `TaskOutput` timeout is a bounded observation, not permission to
restart the still-running worker.
> once in the background and await that task's notification. Preserve full
> artifacts on disk. A failure or timeout leaves the review incomplete.
> For external CI, return and let the next reconcile tick observe it.
> Cancel only tasks you started, using `TaskStop` with their exact task IDs.
> If cancellation is unavailable, report the task ID and return. Cleanup is
> limited to your own worktree and files; process-name kills and synthetic
> background sleep tasks are forbidden in this shared fleet.

The shared container hook applies to coordinators and review children. It
rejects process-name cleanup, background sleep commands, and standalone waiting
echoes. These checks guide behavior; the controller's private tmux socket and
separate server UID enforce the supervisor boundary (LLP 0077). The runner owns
CLI timeouts. A bounded wait timing out does not authorize restarting a worker.

### Admission — heal broadly, start narrowly (LLP 0060)

Expand Down Expand Up @@ -212,10 +221,10 @@ tick's log lines (R2 — nothing may follow this destructive act):
`tick: family=autophagy action=recycle detail=context=<N> threshold=<T>`, then
**respawn the pane** — the tick's last act:
```sh
tmux respawn-pane -k "claude --model 'claude-opus-5[1m]' --dangerously-skip-permissions '/loop /neutral-reconcile'"
tmux respawn-pane -k "ANTHROPIC_DEFAULT_FABLE_MODEL=claude-fable-5-1 claude --model 'opus[1m]' --dangerously-skip-permissions '/loop /neutral-reconcile'"
```
**Pin the model** to the 1M-context Opus 5 (the worker tier, matching `neutral
start` — LLP 0020): an unpinned respawn silently reverts the fresh orchestrator to
**Select `opus[1m]`** for the 1M-context worker tier (matching `neutral
start` — LLP 0020): a respawn without `--model` silently reverts the fresh orchestrator to
the machine's session default, which may be a different tier or a 200K window too
small for the autophagy threshold T (LLP 0013). Single-quote the `[1m]` token so `sh`
doesn't glob the brackets. **Keep `--dangerously-skip-permissions`**: the loop is
Expand Down Expand Up @@ -296,23 +305,33 @@ model's failure just re-opens the gap — so cheap models run wherever a verifie
the result, and the strongest is reserved for judgement no machine re-checks. When you
dispatch a worker below, pass the tier's model as the sub-agent's `model`:

- **Judgment tier — `claude-fable-5-1`, at `high` effort.** Output no verifier re-derives, where
The Agent tool accepts family aliases. Launch with
`ANTHROPIC_DEFAULT_FABLE_MODEL=claude-fable-5-1` so `model: "fable"` selects
Fable 5.1; `neutral start` and the Docker image set this binding. The Workflow
keeps its explicit model ID. After a CLI or model-binding update, recycle the
running loops and verify the response model in recorded usage.

- **Judgment tier — `fable`, at `high` effort.** Output no verifier re-derives, where
an error propagates: the **Designer**, the **Impl-designer**, and the **triage** rung.
Run Fable 5.1 at **`high`**, not Claude Code's `xhigh` default — Fable 5.1 at `high` still
exceeds prior models at their ceiling, so it's a low-risk cost lever on the priciest
tier. The implement Workflow enforces this via `agent({ effort: 'high' })`; the **Agent
tool has no per-call `effort` override**, so the Designer/Impl-designer/triage inherit
the **session** effort — run the orchestrator loop at `high` if you want them capped
there too.
- **Worker tier — `opus` (Opus 5).** Bounded work behind a hard gate: **conflict
- **Worker tier — `opus` (Opus).** Bounded work behind a hard gate: **conflict
resolution**, **issue-fix**, the Claude half of **review**, and the **orchestrator
itself** (pinned at launch — LLP 0020; the tick is mechanical, the CLI decides every
itself** (selected explicitly at launch — LLP 0020; the tick is mechanical, the CLI decides every
rung).
- **Mechanical tier — `sonnet`, or `haiku` for pure CLI relay.** Fully verifier-gated
execution: **task implementation** and its **serial merger**, **fix-ci**,
**review-fix** agents, and **derive-ready** (haiku). The implement Workflow already
sets these per `agent()` call.

The `opus` and `sonnet` aliases follow the versions provided by the installed
Claude Code and provider. Keep Claude Code current; `ANTHROPIC_DEFAULT_OPUS_MODEL`
and `ANTHROPIC_DEFAULT_SONNET_MODEL` can override these aliases.

**Retry escalation (LLP 0021/0022).** A task's *first* attempt starts at the tier its
planner-rated `complexity` seeds (1–3 mechanical, 4 worker, 5 judgment; absent ⇒
mechanical). It retries in place until it exhausts that tier's budget of **verified**
Expand All @@ -322,7 +341,7 @@ escalation changes *which model retries*, never *what counts as done*. The imple
Workflow's wave loop owns this ladder end-to-end; the other rungs below take a single
tier per their heading.

## Fan-out worker: Designer (pipeline) — judgment tier (`claude-fable-5-1`)
## Fan-out worker: Designer (pipeline) — judgment tier (`fable`)

Goal: every live request is `@ref`'d by a `design` LLP. Plan the **whole** backlog
up front, then mint only the groups covered by this tick's reserved admission slots
Expand Down Expand Up @@ -350,7 +369,7 @@ up front, then mint only the groups covered by this tick's reserved admission sl
the remote branch); then `cd <repo> && git worktree remove --force "$WT"`.
4. **Verify:** `neutral backlog` is now **empty**. Never commit a design to the target branch.

## Fan-out worker: Impl-designer (pipeline) — judgment tier (`claude-fable-5-1`)
## Fan-out worker: Impl-designer (pipeline) — judgment tier (`fable`)

Goal: every implementable `design` LLP has a `plan` LLP on its `integration/<slug>`
branch. A design is implementable two ways: **neutral-minted** (already on
Expand Down Expand Up @@ -382,7 +401,7 @@ content edit — immutability holds) so the merged change set reads as shipped (
Encode real code dependencies in `deps`. **Rate each task's `complexity` 1–5**
(LLP 0022) — your judgement, made here with the whole design in view, seeds the
first implementation attempt's model tier: **1–3** a mechanical task (Sonnet),
**4** needs the worker tier (Opus 5), **5** needs judgement (Fable 5.1). Rate for
**4** needs the worker tier (Opus), **5** needs judgement (Fable 5.1). Rate for
the *hardest* part of the task; be honest, not generous — the rating only seeds
the entry rung and a verified failure still escalates (LLP 0021), so under-rating
costs one climbing attempt, over-rating overpays. Omit `complexity` only when you
Expand Down Expand Up @@ -534,9 +553,14 @@ which replies are new.
- **`review`** (rung 3, head not yet reviewed): dispatch the review in its **own
worktree** (never the main checkout, LLP 0012) — `dual-review` does a `gh pr
checkout --detach` *in place* and **refuses on a dirty tree**, so it must run in a
clean, isolated checkout. Run the review — `dual-review` when `command -v codex`
succeeds, else `code-review` — on the PR number; the review itself is **worker-tier**
work (LLP 0020 — Codex, when present, is the independent second family). **Capture
clean, isolated checkout. **First review:** run `dual-review` when `command -v codex`
succeeds, else `code-review`, on the full PR. **Re-review after changes:** when
`previousReviewSha` is present, read
[references/incremental-review.md](references/incremental-review.md) before
dispatch; pass its verified baseline, prior findings, and delta scope to every
reviewer, including nested helpers. Use the same reviewer families with that
explicit scope. The review itself is **worker-tier** work (LLP 0020 — Codex,
when present, is the independent second family). **Capture
the head SHA you reviewed** (the `headSha` from `neutral prs`). For each finding, record a numbered disposition: `fix` for a current-PR
defect, `defer` for safely out-of-scope work, `reject` with evidence, or
`blocker` for an unresolved shipping risk. A pre-existing defect can still
Expand All @@ -551,13 +575,16 @@ which replies are new.
`clean` when the review found nothing actionable, `findings` when it found any
(fixed or not; LLP 0029) — followed by the full review a human can act on: the
verdict, each finding with severity and evidence (file:line), and what was fixed.
State the review scope, PR target branch, and comparison base SHA; incremental
rounds also include the previous review link and prior finding outcomes.
**Post the record whatever the outcome** — a round that leaves no comment did not
happen (`reviewRounds` counts these comments), and an unrecorded blocked round
would re-review the same head forever. No separate `gh pr edit`: the comment is
the single act. If you fixed findings the head has since moved, so the next tick
re-reviews the new head (round 2); if the review was `clean` the record covers
incrementally reviews the new head (round 2, LLP 0078); if the review was `clean` the record covers
the current head. If findings remain at an unchanged head, the next tick
performs narrow triage instead of repeating the review. The CLI bounds full reviews to **N=2** rounds
performs narrow triage instead of repeating the review. The CLI bounds reviews
(full or incremental) to **N=2** rounds
and also returns `triage` for unchanged findings — plus any budget a human granted in the thread with a
`neutral: rounds +N` comment (LLP 0059; the CLI folds grants into the cap, so trust
the `action` field as ever — no skill-side arithmetic).
Expand Down
64 changes: 64 additions & 0 deletions .claude/skills/neutral-reconcile/references/incremental-review.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# Incremental re-review

@ref LLP 0078 [implements] — changed heads reuse verified review evidence

Use this procedure when `action: review` includes `previousReviewSha`. The
existing round cap, reviewer independence, finding dispositions, and final-head
ship-risk gate still apply.

1. **Verify the baseline.** Read the latest marker-signed review comment in full,
including its numbered findings and linked evidence; follow earlier review
links when this baseline was itself incremental. Match its marker to
`previousReviewSha`; resolve that value and the observed current head to full
commit SHAs. Fetch missing objects once. Verify with
`git merge-base --is-ancestor <previous-reviewed-SHA> <current-head-SHA>`.
A legacy bare marker without the underlying review is insufficient evidence
for incremental coverage. Establish that the PR target is unchanged from the
previous report or GitHub's base-change history; an unknown or changed target
requires full review. If the head or latest record changed since the CLI
observation, return to observation before dispatch.
2. **Set the scope.** With a verified baseline, use
`git diff <previous-reviewed-SHA> <current-head-SHA>` — the two committed
trees, not the whole PR against its target. Read enough surrounding code,
callers, tests, and applicable LLPs to assess the delta's effects. Account for
each prior finding: verify claimed fixes in the committed tree and with
targeted regression evidence; carry unresolved findings forward; retain
supported deferrals/rejections unless the delta invalidates their evidence.
Prior settled conclusions stand where their assumptions still hold. An empty
delta needs verification of that fact and outstanding findings, not another
broad scan.
3. **Widen from evidence.** Expand to affected interactions when the delta changes
an interface, invariant, or dependency used by otherwise unchanged code.
Use a full PR review when the previous commit/report is unavailable, history
was rewritten so ancestry cannot be verified, the PR was retargeted, or a
redesign or conflict resolution invalidates the earlier review broadly.
A merged target update is part of the delta; inspect its integration effects
and widen only as needed. A new head SHA alone is not a reason to start over.
Record the concrete reason and expanded files/invariants before doing the
additional work. A broad scan that happens to find something is not a scope
justification after the fact.
4. **Dispatch that scope explicitly.** Give every reviewer the exact previous
and current SHAs, previous review link and findings, delta command, and any
justified expansion. Require nested reviewers to inherit them. For an
incremental round, invoke `code-review` / `dual-review` only through a mode
that honors this comparison. If the available skill defaults to the whole PR
or silently starts broad nested reviews, use explicitly scoped reviewers
from the same required model families instead. Tool limitations alone do not
authorize a full re-review. Preserve independent verification and one
marker-signed round; nested helpers do not post additional round markers.
5. **Record and re-observe.** The normal `neutral-review` comment still names the
full head SHA actually reviewed and counts as one round, including an
incremental round. Its prose states `Scope: incremental <previous>..<head>`
(or `Scope: full — <reason>`), links the previous review, lists each prior
finding's verified outcome, new findings, tests, and any expanded scope.
`clean` requires both no new actionable findings and every prior finding
fixed with evidence or safely disposed of; unresolved findings cannot become
clean merely because the delta introduced none. If fixes are pushed, record
the reviewed pre-fix head as usual and return to observation. Recheck the
current PR head before publication; concurrent head movement returns to
observation and never receives a marker for unreviewed code.

Completion means the delta and affected interactions have been reviewed,
every prior finding is accounted for, and the recorded scope is backed by the
actual git comparison. Incremental review is an instruction contract, not a
claim that the CLI can verify what a model read.
Loading
Loading