docs: decision log + AGENTS.md/CLAUDE.md working agreement#58
Open
fazpu wants to merge 6 commits into
Open
Conversation
Adopt the ultimate-memory house style (terse canonical decision log + non-negotiable doc rules) so the deliberate design choices are legible to future agents and humans who were not in the conversation. - design/decisions.md — Architecture Decision Log (D1-D6): continuity in files/git (D1); single-worker is deliberate (D2); iteration success = "ran" not "good" (D3); LLM-as-judge, no agent-authored deterministic checks (D4); full autonomy with unresolvable_error as the only last-resort human escape hatch, no preferred human gate (D5); large multi-phase targets driven by the planner/dispatcher double loop from the start (D6). Each entry is self-contained (Decision / Context / Consequences) and anchors claims in code. - AGENTS.md — working agreement: Rule 1 respect the deliberate decisions (don't "fix" D2/D3/D4); Rule 2 autonomy is the goal, the unresolvable_error escape hatch is a LAST resort and no preferred human gate (D5); Rule 3 design/decision docs must be understandable cold by future agents AND humans. - CLAUDE.md — short pointer to AGENTS.md plus the two things that most trip up a change (the deliberate decisions and the autonomy escape hatch), so the two files never diverge. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt
…overy Drop "per-child budgets" from D6's prerequisites (withdrawn as P0.3), and note that double-loop crash recovery is of session/child STATE from files, not of running agent processes — re-adopting a crashed worker's agent subprocesses is not feasible, so a hard worker crash is cleanup, not adoption (proposals P2.5). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt
Record the split we settled on now that we own team-harness: team-harness owns the agent-CLI processes (own process group, persisted pid/pgid/starttime, a reap op — TH-D5), and loopy-loop owns its worker process (pid + heartbeat, verify-dead before reclaim, call reap on recovery). Makes D6 state-recovery safe rather than optimistic; the reaping is a designed team-harness feature we consume, not a /proc-scraping hack. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt
Align D7 with TH-D5 / P2.5: team-harness provides liveness + drain/reap/ignore ops; loopy's default recovery policy is bounded drain (finish + harvest within a timeout), with reap as the escape. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt
…reap-only Last stale reap-only phrasing: loopy's new work is "apply a recovery policy per orphan (default bounded drain, reap as escape)", not "call reap on recovery". Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt
…ovenance Align D7 with the pinned-down drain semantics: drain never synthesizes the dead coordinator's result (D3 false-closure trap); its yield is the agents' completed repo edits (git, D1) plus an explicit salvage record (salvage.json + abandoned_after_drain) so surviving edits are auditable. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Records the main design decisions we've settled on, in the ultimate-memory house style (terse canonical decision log + a short, non-negotiable set of doc rules), and makes agents aware of them — especially the autonomy escape-hatch mechanism.
design/decisions.md— Architecture Decision Log (D1–D6)Each entry is self-contained (Decision / Context / Consequences) and anchors claims in the code, so a future agent or human who wasn't in the conversation can understand it cold:
unresolvable_erroras the only, last-resort human escape hatch — no preferredpaused/human-gate.D3/D4 are the detailed-form-lives-in
success-semantics-and-evaluation.mdentries; this log states the conclusions and cross-links.AGENTS.md— working agreementunresolvable_errorescape hatch is a last resort, exhaust autonomous options first, and do not build/assume a preferred human gate (D5).design/status honest).CLAUDE.mdShort pointer to
AGENTS.mdplus the two things that most often trip up a change (the deliberate decisions and the autonomy escape hatch), so the two files never diverge.Notes
main.🤖 Generated with Claude Code
https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt