Skip to content

propose(contract): evidence-based AGENTS trim, rebased onto current main #1045

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
boshu2 merged 3 commits into from
Aug 16, 2026
Merged

propose(contract): evidence-based AGENTS trim, rebased onto current main #1045

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5baccca
propose(contract): rebase evidence-based AGENTS trim onto current main
boshu2 Aug 5, 2026
7ba4779
docs(evals): qualify legacy estate evidence
boshu2 Aug 16, 2026
1d3f54e
docs(contract): preserve validation and ratchet semantics
boshu2 Aug 16, 2026
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
91 changes: 32 additions & 59 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,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 Down Expand Up @@ -50,11 +48,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.
Default to native Codex plus the local shell; other runtimes only on explicit
request. `ao` is a repository tool, not a session ritual.

## Federated source authority

Expand Down Expand Up @@ -83,50 +79,33 @@ 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 `skills/*/scripts/**/*.py`.
Skill tests retain their documented exemption (ADR-0016, gate-enforced).

## Standard RPI traversal

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 or
colliding context identities, unattested freshness, subject mutation or
digest mismatch, and incomplete changed-path coverage are `NOT_PROVEN`;
proven out-of-scope change is `FAIL`. PASS requires nonempty checked scope,
top-level evidence, 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

Expand Down Expand Up @@ -174,13 +153,7 @@ AgentOps work ownership.
## 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.
50 changes: 50 additions & 0 deletions evals/estate-ablation/PROPOSAL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Deletion proposal — repo operating contract (DRAFT; merge authorized after repair)

> Historical record: the estate-ablation artifacts report 80 scored runs across
> five executor configurations (luna, terra, sol-config, Opus 5, and Fable)
> spanning sweeps 1/2/4, the tier-2 pilot, and probe waves. Those legacy runs
> predate the current evidence contract. Their aggregate count, labels, and
> section classifications are legacy-unverified and non-promotable: they may
> motivate hypotheses, but they do not establish causal effects, current
> behavior, or generalize across models or runtimes. Contemporaneous citations
> do not promote those reports under the current contract.
>
> This PR edits `AGENTS.md` while retaining every current mandatory contract.
> Bo has explicitly authorized merge after these bounded honesty corrections
> and required checks pass. This repair leaves the PR in draft; readiness and
> merge remain separate caller actions.
>
> The historical proposal reported a ~55% cut against its 2026-08-05 subject.
> Current `main` has since added mandatory anti-ceremony, federated-authority,
> and canonical-source contracts, so this rebased diff is a narrower ~21%
> reduction. Those percentages compare document size, not behavior. A separate
> historical Codex sweep reported +8–12% tokens and no execution delta within
> its bounded design; that report is also legacy-unverified and non-promotable.
> It proves neither a generalized token cost nor an execution effect and is not
> current skill-probe coverage.

| Section | Current basis | Action |
|---|---|---|
| Intro + loop diagram | current canonical one-pass RPI orientation | trim |
| Authority and trust | current mandatory trust boundary; the legacy `SURVIVOR` classification remains a non-promotable hypothesis | keep, light trim |
| Honest work and anti-ceremony | current mandatory contract added after the historical subject | keep current-main text |
| Runtime floor | current no-`claude -p` guard plus an explicit runtime boundary | shrink without weakening the prohibition |
| Federated source authority | current federated ownership boundary | keep current-main text |
| Source precedence | current source-authority contract | keep |
| Constraint floor | current Python ratchet, ADR, and active-constraint contract | shrink to enforceable summary |
| Core loop | current standard RPI traversal; legacy sweeps do not establish executor effect | compress without changing semantics |
| Product boundary | current ownership and factory boundary; legacy associations do not establish causation | keep current-main rules |
| Concurrency | current delegation and writer-isolation boundary; the legacy rt-01 report is non-promotable | keep current-main rule |
| Triggered-sources table | current `validate-agents-split` index contract | keep current-main table |
| Closeout | current exact-subject, evidence, and fresh-validation contract | compress without changing semantics |

Rebased net: ~10.5KB → ~8.3KB (-21%). The compression is a current design
proposal; legacy reports supply hypotheses, not proof. Post-study doctrine and
live contract links remain intact.

Follow-ups are separate hypotheses, not findings or work authorized by this PR:
(1) evaluate task-class-gated Codex skill injection suggested by the legacy
sweep-1 report; (2) evaluate closure formats that carry caveats suggested by
the legacy sweep-4 report; (3) leave S3 rules unchanged because they remain
unmeasured under the current contract—the historical wave-1 `BEHAVIORAL` label
is legacy-unverified and non-promotable.