Repository navigation
docs(contract): validate where a mistake is costly; close pre-release gaps - #1189
Merged
Merged
Conversation
…d copy
The Codex plugin shipped skills-codex/, a generated second copy of skills/
with the frontmatter cut to name and description. The bodies were the source
bodies, all 28 catalog rows were parity_only, and `ao skills link` and
`npx skills` already hand Codex the source tree. .codex-plugin/plugin.json
now ships ./skills and the copy is gone, with the generator and everything
that only policed it.
Deleted: skills-codex/ (278 files), skills-codex-overrides/, scripts/lint/,
18 scripts (codex-sync, regen-codex-hashes, register-new-codex-skill,
append-codex-override-entry, mirror-codex-references,
refresh-codex-artifacts, audit-codex-parity.{py,sh},
check-codex-parity-drift, lint-codex-native, smoke-test-codex-skills,
export-claude-skills-to-codex and six validate-codex-* validators), their
tests, four gate-registry entries, and the doctor failure mode
fm-skills-stale-codex-sync.
Kept and reduced to what still has a subject:
- validate-codex-api-conformance.sh now checks skills/ against the facts the
Codex loader enforces (observed with skills/list on codex-cli 0.156.1) and
the explicit-only invocation policy. It stays in regen-all.sh --check.
- skill.runtime-formats, skill.runtime-parity, skill.manifests and
derived.changed-scope keep their skills/ halves.
- ao skills check, ao skills link and ao workflows link find the repo root by
skills/ plus registry.json and PRODUCT.md, not by the skills-codex/ sibling.
Carried over so nothing Codex relied on is lost:
- skills/interview/agents/openai.yaml. Codex reads the invocation policy from
that file, and the generator derived it from disable-model-invocation. It is
now source-owned and the conformance check fails without it.
- skills/_fixtures moved to tests/fixtures/skill-eval. Codex loads every
SKILL.md under the plugin skill tree; the fixtures loaded as a skill named
"Good Skill" and a load error.
prompt.md, .agentops-generated.json and .agentops-manifest.json had no Codex
consumer and are dropped without replacement. The CHANGELOG states what
plugin users lose.
Gate-Loosen-Reason: the generated Codex skill copy is deleted, so check-codex-parity-drift.sh and the four skill.codex-* registry entries that policed only that copy have no subject; every gate over skills/ is kept
Test-Removal-Reason: the removed Go tests covered Codex-copy parity, manifest-hash and plugin-cache sync code paths that are deleted with the copy
…review The contract required a fresh author-distinct validation on every change, a PASS with nothing unchecked, and a re-validation after each repair. A reviewer asked to find problems always finds one, so that combination could not converge and review cost exceeded the cost of the work. The contract and the skills that drive review now say: for an ordinary change the author's checks and CI are the gate. One fresh read is used when the caller asks, when a mistake cannot be cheaply undone after it lands, or when no deterministic check covers the changed behavior. A review is one round, does not re-run checks, reports as defects only what would mislead a user, break install or the CLI, or remove protection for the product, and a repair is confirmed by a check instead of another review. Changed: AGENTS.md, the rpi, validate, implement, orchestrate, craft-goal and navigate skills, the rpi references, two standards references, and the workflow and traversal docs. craft-goal and navigate no longer give every bead its own validation. The fixed-dispatch adapter page now says not to select it for ordinary work. Two wording pins move to the new rule, including one that fails if 'a repair does not start another review' disappears.
- Docs: PRODUCT.md, the docs index, how-it-works, architecture, philosophy, first-value path, migration, CI and scale pages now describe validation as checks and CI plus one fresh read where a mistake is costly. - Remove the fixed-dispatch RPI reference adapter, which modelled repeated review rounds: run_once.py, its tests, its reference page and rpi.feature, plus tests/e2e/rpi-phased-domain.sh, a no-op tombstone kept only so that feature file's scenario link resolved. The conformance script drops the adapter canary and keeps its Validate substrate probe. - That probe now intercepts Git, tracker and delivery calls made in-process; before, they reached the real binaries unnoticed (shown by mutation). - Skill Builder heal.sh --check exits 2 when ao cannot run instead of passing. - The Codex policy check rejects agents/openai.yaml shapes Codex silently drops: non-object interface, dependencies without a tools list, and a boolean spelled other than true or false. - The Skill Builder converter's Codex target no longer writes prompt.md.
boshu2
changed the title
Owner decision. Drop the README's experimental label on goals, and align the README's flow lines with the validation rule: checks for every change, Validate where a mistake is costly.
…it-matters # Conflicts: # CHANGELOG.md # docs/CHANGELOG.md # docs/contracts/codex-skill-api.md # scripts/validate-codex-api-conformance.sh # tests/scripts/codex-skill-conformance.bats
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.
Follows #1188, now merged; main was merged into this branch, so the diff is only this PR's changes.
What changes
The contract required a fresh author-distinct validation on every change, a PASS with nothing unchecked, and a re-validation after each repair. A reviewer asked to find problems always finds one, so that combination could not converge. In practice review cost exceeded the cost of the work.
The contract and the skills that drive review now say:
NOT_PROVENis reported with its gaps instead of being chased.A requested binding verdict keeps its existing PASS rule.
Where
AGENTS.md(still within its 250-line budget, at 249).rpi,validate,implement,orchestrate,craft-goal,navigate, and one example inreverse-engineer.craft-goalandnavigateno longer give every bead its own validation.rpi/references/boundaries.md,outer-goal.md,bounded-adapter.md(now says not to select it for ordinary work), and twodomainstandards pages.docs/agent-workflow-reference.md,docs/architecture/rpi-traversal.md, CHANGELOG.tests/scripts/agents-operating-contract.batsandskills/rpi/scripts/validate.sh. One now fails if "a repair does not start another review" disappears.Not changed
skills/rpi/scripts/run_once.py, the fixed-dispatch adapter with repeated review rounds, is untouched code. Deleting it belongs to the cleanup that follows.Gap fixes (second commit)
Found while checking release readiness; fixed here so the release has one clean pass.
PRODUCT.md, the docs index, how-it-works, architecture, philosophy, first-value path, migration, CI and scale pages now match the skills: checks and CI, plus one fresh read where a mistake is costly.run_once.py, its tests, reference page andrpi.feature) that modelled repeated review rounds, andtests/e2e/rpi-phased-domain.sh, a no-op tombstone kept only so that feature file's scenario link resolved. The conformance script keeps its Validate substrate probe.heal.sh --checkexits 2 whenaocannot run instead of reporting a pass. A new test fails without the fix.agents/openai.yamlshapes Codex silently drops (non-objectinterface,dependencieswithout atoolslist, a boolean spelled other thantrue/false). Any of them made an explicit-only skill implicitly selectable.prompt.md.Checks at
2ae5bbb45:ao gate check --full66 of 66, bats 1,388 pass,tests/skills/run-all.shpass,regen-all.sh --checkcurrent, doc release gate pass, Skill Builder integration tests 9 of 9.Checks
ao gate check --full66 of 66, bats 1,388 pass,tests/skills/run-all.shpass,regen-all.sh --checkcurrent, doc release gate pass. No review round, per the rule this PR introduces: it changes instructions, not a release or a security boundary, and CI covers the rest.