Skip to content
Draft
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
130 changes: 37 additions & 93 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,7 @@ RPI -> Plan -> Implement -> fresh Validate -> report and stop
```

No fresh independent judgment over the exact subject means the experiment is
not proven. Persist `verdict.v2` only when the caller requests machine-readable
evidence or a declared downstream consumer requires it. AgentOps does not own
what the caller does next.
not proven.

## Authority and trust

Expand All @@ -26,11 +24,9 @@ what the caller does next.

## Runtime floor

- Never run `claude -p` or `claude --print`, directly or indirectly.
- Default to native Codex plus the local shell. Start another runtime or
orchestration substrate only when the user explicitly requests it.
- Do not run `ao session bootstrap`, lookup, or archive commands as startup
ritual. The `ao` CLI is an explicit repository tool, not a session runtime.
Never run `claude -p` or `claude --print`, directly or indirectly (hook-enforced).
Default to native Codex plus the local shell; other runtimes only on explicit
request. `ao` is a repository tool, not a session ritual.

## Source precedence

Expand All @@ -43,102 +39,50 @@ Edit source owners and regenerate projections through the owning command.

## Constraint floor

- A plan, duel, or design becomes authoritative only if its inputs include the
active constraints that apply to its scope: relevant ADRs (`docs/adr/`),
blocking gates (`cli/internal/gates/`, `scripts/check-*.sh`), and this
contract. A synthesis frozen without an active constraint is invalid, not
grandfathered.
- Skill logic ships in Go via `ao`; skill scripts are thin POSIX shell glue.
No new `skills/*/scripts/**/*.py` (ADR-0016, enforced by
`scripts/check-skill-python-ratchet.sh`; tests keep their documented
exemption). Grandfathered Python is migration debt, not precedent.
Active constraints (ADRs in `docs/adr/`, blocking gates in
`cli/internal/gates/` and `scripts/check-*.sh`, this contract) are inputs to
any authoritative plan or design; a synthesis frozen without them is invalid.
Skill logic ships in Go via `ao`; no new skill Python (ADR-0016, gate-enforced).

## Core loop

1. **Plan once.** Resolve the existing bead or caller intent and shape one
active behavior there. Acceptance, non-goals, scope, and the first useful
check stay in that source; AgentOps does not require a model-authored plan
packet that duplicates it. If no durable tracker artifact exists, the runtime
snapshots the resolved intent bytes under their content digest so fresh
contexts can consume the exact same source. Once the caller accepts the
shaped intent, Plan is closed: further planning, audit, or review lanes over
the same intent require new explicit caller authorization.
2. **Implement once.** Execute one bounded RED -> GREEN -> refactor experiment.
The runtime derives the content manifest, actual changed paths, coverage
completeness, and factual check receipts; the model does not transcribe a
candidate packet.
3. **Validate once, fresh.** A distinct context verifies the intent-source
digest, subject identity, scope, evidence, and acceptance, then returns one
`PASS | FAIL | NOT_PROVEN` result. Missing or colliding context identities,
unattested freshness, subject mutation, or incomplete changed-path coverage
is `NOT_PROVEN`; proven out-of-scope change is `FAIL`. PASS requires nonempty
checked scope, top-level evidence, and evidence for every criterion.
Persistence is conditional: Validate writes `verdict.v2` only for a caller
request or a declared downstream consumer.
4. **Report and stop.** RPI reports `PASS | FAIL | NOT_PROVEN`, or the report-only
statuses `NOT_PLANNED | NOT_BUILT`. It emits no next action and performs no
automatic revision. Two consecutive control artifacts (plans, audits,
reviews, prompts, reports) with no new implementation evidence end the run
— `NOT_BUILT` when no subject exists yet, otherwise a hard stop reporting
the existing subject's status; reports lead with the subject (paths
changed, commits, tests), never with artifact counts.

A caller may revise the bead or caller intent and start a new invocation.
Changing acceptance changes that source; AgentOps does not create a parallel
revision packet. Learn is an optional later consumer of verdict collections and
cannot change core outcomes.
1. **Plan once.** Shape one active behavior in the existing bead or caller
intent — acceptance, non-goals, scope, first check. Once accepted, further
planning over the same intent needs new explicit authorization.
2. **Implement once.** One bounded RED -> GREEN -> refactor experiment; the
runtime derives the manifest, changed paths, and check receipts.
3. **Validate once, fresh.** A distinct context verifies subject identity,
scope, evidence, and acceptance: `PASS | FAIL | NOT_PROVEN`. Missing
identity/freshness or incomplete coverage is `NOT_PROVEN`; proven
out-of-scope change is `FAIL`. PASS requires evidence for every criterion
and an empty `not_checked`. Persist `verdict.v2` only for a caller request
or declared consumer.
4. **Report and stop.** Report the result; emit no next action; no automatic
revision. Two consecutive control artifacts with no new implementation
evidence end the run. Reports lead with the subject, never artifact counts.

A caller may revise the intent and start a new invocation. Learn is an
optional later consumer and cannot change core outcomes.

## Product boundary

AgentOps reads or refines caller-owned intent, runs one bounded experiment,
establishes exact content identity, and obtains fresh independent judgment. It
can persist that judgment as standalone evidence when requested. It owns no retry,
budget, queue, work ownership, Git, closure, release, landing, or delivery
transition. Consumer repositories keep their own direct-push, PR, CI, merge,
rollback, and release policy.

Premortem, Postmortem, Council, and genie skills are caller-selected judgment
strategies. NTM, Agent Mail, Gas City, swarms, and other factory tools are
optional adapters. Optional strategies and adapters never become core
dependencies or lifecycle authorities.

A selected factory's internal control plane is operated only through that
factory's own doors: its coordinator (for Gas City, the Mayor via mail), its
doctor, and its supervisor start/stop from outside. An agent never creates,
scales, or repairs factory-internal sessions by hand — a hand-made session can
squat a canonical name and block the factory's own reconciler. Dispatch
belongs to the coordinator too: the agent authors one source intent bead and
hands its id over; the coordinator authors the workflow beads and launches the
runs. The agent lane into a factory is: author source intent, mail the
coordinator, read state, judge results.
establishes exact content identity, and obtains fresh independent judgment.
It owns no retry, budget, queue, work ownership, Git, closure, release, or
delivery transition. Judgment strategies (premortem, council, ...) are
caller-selected; factories (NTM, Gas City, ...) are optional adapters and are
operated only through their own doors — the agent lane is: author source
intent, hand it to the coordinator, read state, judge results.

## Concurrency

One agent and one writer are the default. Use multiple lanes only when the user
requests delegation. Concurrent writers require disjoint write scopes and
separate isolation; shared paths serialize. These are runtime safety rules, not
AgentOps work ownership.

## Triggered sources

| Trigger | Canonical owner |
|---|---|
| Core loop or evidence-contract change | `docs/architecture/operating-loop.md`, `schemas/*.schema.json` |
| CLI command or flag | `cli/cmd/ao/`, then generated `cli/docs/COMMANDS.md` |
| Skill behavior or inventory | `skills/<slug>/SKILL.md`, generated `docs/SKILL-ROUTER.md` |
| Codex projection | `docs/contracts/codex-skill-api.md`, `skills-codex-overrides/catalog.json` |
| Deterministic checks | `docs/CI-CD.md`, `cli/internal/gates/` |
One agent, one writer by default; delegated lanes need disjoint write scopes
and separate isolation — shared paths serialize.

## Closeout

Inspect the final subject, map acceptance to evidence, disclose `checked` and
`not_checked`, and obtain one fresh validation result over the exact content.
`not_checked` names in-scope acceptance surface that went unverified, so a PASS
has none by construction and any entry makes the result `NOT_PROVEN`. Scope
limits are disclosed, never deleted: a bounded proof of a criterion belongs in
that criterion's `reason`, a declared non-goal belongs to the intent source
(optionally restated as an evidence-backed boundary criterion), and residual
risk belongs in this report. Include a verdict reference only when persistence
was requested. Report residual risk plainly. Git status, pushing, merging,
release, and rollback are handled by the caller's repository policy, outside
semantic completion.
`not_checked` (any entry makes the result `NOT_PROVEN`; scope limits are
disclosed, never deleted), and obtain one fresh validation over the exact
content. Git, push, merge, release, and rollback belong to the caller's
repository policy.
33 changes: 33 additions & 0 deletions evals/estate-ablation/PROPOSAL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Deletion proposal — repo operating contract (DRAFT, Bo ratifies)

> Evidence base: 80 scored runs across 5 executors (luna, terra, sol-config,
> Opus 5, Fable) — sweeps 1/2/4 + tier-2 pilot + probe waves. Every verdict
> cites its measurement. This PR EDITS CLAUDE.md per the verdicts; it merges
> only on Bo's explicit ratify. Honest headline: the evidence does NOT
> support a performative 80% cut here — it supports a ~55% cut with
> per-section receipts, because sweep 4 caught Claude executors APPLYING
> parts of this contract mid-run (citing authors-cannot-self-PASS and
> report-and-stop productively). The 80%-equivalent waste on this estate
> lives on the CODEX surface (always-on skills injection: +8-12% tokens,
> zero measured execution effect — separate mechanism PR).

| Section | Verdict | Evidence | Action |
|---|---|---|---|
| Intro + loop diagram | KEEP | orientation; 3 lines | trim |
| Authority and trust | **SURVIVOR** | Opus/Fable t03/t04 applied its rules mid-execution (sweep 4); the one contract surface observed changing behavior | keep, light trim |
| Runtime floor | ENFORCED | no-claude-p hook carries it; prose never observed load-bearing | shrink to pointer |
| Source precedence | KEEP (cheap) | orchestrator-facing, 4 lines | keep |
| Constraint floor | ENFORCED | python-ratchet gate + ADR carry it | shrink to pointer |
| Core loop | PRODUCT | dead for executors (sweeps 1-2: zero effect on GPT-line); alive as orchestrator spec (this session ran it all day) | compress ~50% |
| Product boundary | PRODUCT | boundary behavior; sweep-4 scope discipline consistent with it | compress |
| Concurrency | MOSTLY-NATIVE | rt-01: correct collision handling unaided; worktree/reservation tooling enforces | shrink to 2 lines |
| Triggered-sources table | DEAD (reference, not instruction) | never observed load-bearing in any of 80+ transcripts | delete; docs pointer remains |
| Closeout | PRODUCT | validate flow carries mechanics | compress |

Net: 9.2KB → ~4.1KB (-55%), zero binding-rule weakening — compressions
reword, deletions remove only prose whose rule lives in a hook, a gate, or a
doc. Follow-ups (separate PRs, not this one): (1) codex adapter scopes skill
injection by task class (sweep-1 receipt); (2) closure-artifact formats that
carry caveats (sweep-4 disclosure-lives-in-chat finding); (3) S3 rules-file
lever unmeasured — rules stay untouched (wave-1 measured their INLINE form
BEHAVIORAL; do not delete unmeasured surface).
Loading