Skip to content

Settlement as a local-first /settle skill: shared consensus engine, settle CLI, punitive ledger, repo cleanup - #10

Merged
jucasoliveira merged 7 commits into
masterfrom
claude/ai-standards-multi-agent-tasks-88qrxa
Jul 21, 2026
Merged

Settlement as a local-first /settle skill: shared consensus engine, settle CLI, punitive ledger, repo cleanup#10
jucasoliveira merged 7 commits into
masterfrom
claude/ai-standards-multi-agent-tasks-88qrxa

Conversation

@jucasoliveira

@jucasoliveira jucasoliveira commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

Summary

This PR repositions Settlement from a daemon-only multi-LLM consensus service into a local-first agentic skill, while keeping the existing HTTP service intact on a shared engine. It contains four design documents, a repo cleanup, a behavior-preserving refactor, the new settle CLI + /settle skill, and the repo's first tests and PR-triggered CI.

Design docs (docs/)

  • AI_MODERNIZATION_ROADMAP.md — audit of the codebase against modern agentic practices (multi-agent tasks, loop engineering, graph engineering) with a phased roadmap.
  • SETTLEMENT_GRAPH_AGENTS_DESIGN.md — graph-spawned agent panels that settle code changes; knowledge-graph blast-radius policy; decisions as queryable precedent.
  • SETTLE_SKILL_MEMORY_AND_PUNITIVE.md — persistent memory tiers, the punitive Proof-of-Adequacy ledger (agents/skills/loops), and packaging: local-first skill, cloud as the paid tier.

Repo cleanup

  • Removed the discord/ hello-world bot stub (never integrated; history preserves it).
  • Untracked the accidentally committed 30 MB go/settlement binary and .DS_Store; rewrote both .gitignores (anchored binary names, OS junk, env files, .settlement/verdicts/ scratch). Note: the blob remains in git history — purging it (git filter-repo + force-push) is a separate opt-in follow-up that would shrink clones from ~30 MB to ~1 MB.
  • README now opens with a repository-layout table pointing at the design docs.

Shared consensus engine (go/consensus)

The vote-tallying engine (exact/semantic/numeric/merge strategies, weighted voting, merged-reasoning extraction) is extracted verbatim from core/queue_manager.go into a dependency-free package (no gRPC, no pool, no SDKs). The single LLM coupling is injected via a Synthesizer interface — nil runs fully offline via the existing algorithmic fallbacks. core keeps type aliases and thin checkConsensus/mergeConsensus wrappers, so server behavior and JSON contracts are unchanged (verified by build, vet, tests, and a live /api/v1/stats smoke). Also fixes two pre-existing go vet warnings.

settle CLI (go/cmd/settle, stdlib-only, no daemon, no network)

  • settle init — scaffold .settlement/ (config.json, ledger.json, decisions.jsonl; verdicts/ stays untracked scratch)
  • settle panel — deterministic panel spec for a diff: personas from config, weights from the ledger, size from diff stats; quarantined personas seat as weight-0 shadow voters
  • settle tally — adjudicates persona verdict JSONs through the shared engine (exact_match over approve/reject/revise), appends the decision; exit codes 0 approve / 2 reject-revise / 3 no consensus
  • settle outcome — records ground truth (held/reverted) as an append-only event and applies the punitive rule: clamp(VP + 0.05·aligned − 0.15·misjudged − 0.02·(VP−1), 0.1, 2.5), quarantine below 0.4
  • settle log / show / ledger — read decisions and voting powers

All schemas carry settle/*@1 version tags for forward compatibility with the planned graph substrate. (Deviation from the original plan: config.json instead of config.yaml, keeping the CLI dependency-free.)

/settle skill (skill/settle/)

Platform-agnostic SKILL.md: any host assistant captures the diff, builds the panel via the CLI, spawns one independent subagent per seat, collects verdict JSONs, tallies, and reports with dissents surfaced. Ships five persona prompts: correctness, security, api-contract, simplicity, tests.

Tests + CI

  • go/consensus and go/settle test suites (the repo previously had zero tests): all four strategies, weighted-vote semantics, rate-limit handling, panel sizing, ledger asymmetry (penalty > reward; vindicated dissent gains), quarantine engagement.
  • scripts/settle-dryrun.sh — offline E2E: init → panel → canned verdicts → tally (approve with dissent) → outcome reverted → ledger movements asserted.
  • .github/workflows/test.yml — build + vet + test + dry run on every PR and push to master. The existing manual deploy workflow is untouched.

Verification

  • cd go && go build ./... && go vet ./... && go test ./... — green.
  • bash scripts/settle-dryrun.sh — PASS (approvers 1.0→0.85, vindicated dissenter 1.0→1.05 after a reverted approval).
  • Server smoke: GET /api/v1/stats responds identically post-refactor.

🤖 Generated with Claude Code

https://claude.ai/code/session_016Zycxwvy6wPQwiyRSmmJJz

Generated by Claude Code

claude added 7 commits July 21, 2026 10:13
@claude
chore: remove discord bot stub
6a1b03f 
The Rust/Shuttle bot was a hello-world proof of concept (single /ping
command) with no integration to the settlement engine. History preserves
it if a Discord surface returns later.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Zycxwvy6wPQwiyRSmmJJz
@claude
chore: untrack build artifacts and fix gitignores
9c2df86 
Removes the accidentally committed 30 MB go/settlement binary (arm64
build output — it was the entire git pack weight) and .DS_Store from
tracking. go/.gitignore now covers the settlement and settle binary
names; the root .gitignore replaces the Python template with entries
for OS junk, Go/Node build output, env files, and .settlement/verdicts
scratch, keeping the LaTeX-artifact ignores (whitepaper sources and PDF
remain tracked).

Note: the binary remains in git history; purging it (git filter-repo +
force-push) is a separate opt-in follow-up that would shrink clones
from ~30 MB to ~1 MB.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Zycxwvy6wPQwiyRSmmJJz
@claude
docs: add repository layout section to README
bac1912 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Zycxwvy6wPQwiyRSmmJJz
@claude
refactor: extract shared consensus package from queue manager
10d9661 
Moves the vote-tallying engine (exact/semantic/numeric/merge strategies,
weighted voting, merged-reasoning extraction) verbatim out of
core/queue_manager.go into a new settlement-core/consensus package with
no gRPC, pool, or SDK dependencies. The one LLM coupling (OpenAI
synthesis) is injected via a Synthesizer interface; nil selects the
existing offline algorithmic fallbacks. core keeps type aliases and
thin checkConsensus/mergeConsensus wrappers, so server behavior and
JSON contracts are unchanged. Adds the repo's first test suite:
table-driven coverage of all four strategies, weighted-vote semantics,
rate-limit handling, and reasoning extraction. Fixes two pre-existing
go vet warnings (non-constant fmt.Errorf format strings).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Zycxwvy6wPQwiyRSmmJJz
@claude
feat: settle CLI — local panel reviews with punitive ledger
a2c1e6c 
New settlement-core/settle package + settle binary (stdlib-only,
per-command, no daemon, no network):

  settle init     scaffold .settlement/ (config.json, ledger.json,
                  decisions.jsonl, untracked verdicts/ scratch)
  settle panel    deterministic panel spec for a diff: personas from
                  config, weights from the ledger, size from diff stats;
                  quarantined personas seat as weight-0 shadow voters
  settle tally    adjudicate persona verdict JSONs through the shared
                  consensus engine (exact_match over approve/reject/
                  revise), append the decision record; exit codes
                  0 approve, 2 reject/revise, 3 no consensus
  settle outcome  record ground truth (held|reverted) as an append-only
                  event and apply the punitive voting-power rule:
                  clamp(VP + 0.05*aligned - 0.15*misjudged - 0.02*(VP-1),
                  0.1, 2.5), quarantine below 0.4
  settle log/show/ledger  read decisions and voting powers

All schemas carry versioned tags (settle/*@1) for forward compatibility
with the planned graph substrate. Binary-name gitignore entries are
anchored so they no longer shadow the new package directories. Tests
cover store round-trips, panel sizing, tally outcomes with dissent,
ledger asymmetry (penalty > reward, vindicated dissent gains), and
quarantine engagement.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Zycxwvy6wPQwiyRSmmJJz
@claude
feat: /settle skill — panel-review orchestration + persona prompts
9077707 
Platform-agnostic SKILL.md instructing any host assistant how to run a
settlement review: capture the diff, build the panel via the settle CLI,
spawn one independent subagent per persona seat, collect verdict JSONs,
tally, and report the decision with dissents surfaced. Five reviewer
personas (correctness, security, api-contract, simplicity, tests), each
scoped to a single question with severity calibration and the verdict
contract enforced.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Zycxwvy6wPQwiyRSmmJJz
@claude
ci: build/vet/test workflow with settle CLI dry run
7ad9cd6 
New test.yml runs on pull requests and pushes to master: go build, go
vet, go test across all packages, then an end-to-end settle CLI smoke
(scripts/settle-dryrun.sh: init -> panel -> canned verdicts -> tally ->
outcome, asserting the consensus result and punitive ledger movements).
The existing manual deploy workflow is untouched.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Zycxwvy6wPQwiyRSmmJJz
@jucasoliveira
jucasoliveira merged commit db599dc into master Jul 21, 2026
1 check passed
@jucasoliveira jucasoliveira mentioned this pull request Jul 21, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@jucasoliveira @claude