Retire the 3.x plugin curl/PowerShell installers as tombstones, delete the
plugin-cache helpers, and rewire CI/doctor/conformance onto the canonical
checkout + ao skills link path. Keep install-bd and the opt-in operator scripts.
Co-authored-by: Cursor <cursoragent@cursor.com>
Migrate SYSTEM and AGENTS-{WORKFLOW,CI,CODEX,RUNTIME} into docs owners,
retarget consumers, rewrite the split gate, and craft-densify AGENTS,
README, PRODUCT, and GOALS under the documentation authority graph.
Co-authored-by: Cursor <cursoragent@cursor.com>
Harvested FRESH against current main per the bead spec (PR predates the 07-03/07-04
churn; PR flow retired — direct-main + pawl is the landing path).
Item 1 (from 0c9b1582e): skill-builder init.sh/build.sh honor
SKILL_BUILDER_REPO_ROOT (HEAL_REPO_ROOT pattern) so the whole scaffold pipeline
— skills/, dispositions ledger, codex catalog, registry regen — points at a
scratch repo in tests; test_skill_builder.bats scaffolds into a setup_file
scratch copy + isolation test proving no bats-builder-test-* trace lands in the
real tree (14/14 green, 0 traces). append-skill-disposition.sh appends
newline-safely (regression test; 12/12 green).
Item 2 (from 30f7b4f80): regen-codex-hashes.sh keys manifest skills[] by name
— last row wins, one row per name; live run collapsed 102 rows -> 62 (the 40-dup
pathology the PR described), 0 duplicate names. regen-codex-hashes-only.bats
regression suite green. skill-builder twin resynced (codex-sync --force) +
hash bookkeeping refreshed; validate-codex-generated-{manifest,artifacts} green.
Item 3 (compile->curate merge) deliberately NOT harvested here: superseded by
the audit retire wave (l6ic.12) which lands the end state (compile+curate ->
post-mortem) in its own arc. #892 closes as superseded after this lands.
Demote compile, forge, flywheel, curate, operationalize, inject (the SKILL, not
the ao inject command) to the experimental tier (reusing the tier .21 created),
and DROP their Codex twins — the corpus/flywheel skill-surface cut.
Twin-drop mechanism: a new `excluded` catalog treatment. codex-sync.sh reads the
excluded set and skips generation (closing the .18 "missing twin regenerated"
escape hatch); validate-codex-override-coverage.sh accepts `excluded` and asserts
the twin+override dirs are truly absent (an excluded record can't mask an orphan).
Removed the two hard skills-codex/inject/* requirements from
validate-codex-rpi-contract.sh + check-hookless-cold-start.sh; pruned
forge/compile/flywheel/inject from images/codex/manifest.json CORE (else
verify.sh / ao codex health break). git rm'd the 6 twin dirs (53 files).
/forge, /compile, /flywheel still resolve (skills kept), with honest
"(experimental — kept, not primary)" notes in operating-loop move 7 / AGENTS.md /
SKILL-ROUTER. regen-check, coverage, parity-drift, cold-start, images verify.sh,
manifests all green; registry all 6 = experimental.
Highest-leverage maintenance move: editing an AMBIENT (non-spine) skill no
longer restains its Codex twin. Regeneration is now gated on the source skill's
`spine: true` frontmatter (the same signal check-spine-integrity.sh pins).
- codex-sync.sh: a non-spine skill whose twin is already complete + registered
is skipped in both --check and regen (frozen in place). A MISSING twin (new
skill) is still generated so validate-codex-override-coverage.sh stays satisfied;
`--force --only <slug>` still deliberately regenerates a frozen twin.
- regen-codex-hashes.sh: for non-spine skills the source_hash is NOT recomputed
from a changed source (frozen/authoritative); generated_hash is still recomputed
so a real twin-content change is still caught.
- validate-codex-lifecycle-guards.sh: partitioned entry/closeout/tracker
assertions into spine (hard require) vs frozen-ambient (assert-if-present), so
the guard survives the freeze and any later twin removal by .19.
NO twin deleted (count unchanged); coverage/parity-drift/lifecycle/cold-start/
manifest all green. Proven: editing account-rotation leaves its twin
byte-identical while editing spine skill `validate` still restains its twin.
age-0js4 asked codex-sync to auto-refresh existing twins' references on source
change. Scoping (the bead's required first step) + a cross-family duel found the
premise unsafe for bespoke twins: they are HAND-MAINTAINED in full — body AND
references. Categorizing every bespoke reference vs transform(source): 74
in-sync, 21 stale, but DOZENS are genuine Codex-condensed hand-rewrites (e.g.
research/references/data-flow-from-entry-points.md: 85 source lines deleted, 56
added) and 85 source refs are intentionally absent. A blanket auto-refresh would
clobber the hand-authored copies.
Resolution (codex duel: constructive->B+ manifest, adversarial cost/value->C):
for a P2 with a sibling DETECTION bead (age-odv), the proportionate call is to
CODIFY the contract, not build a ~240-file tracked/bespoke classification regime.
codex-sync correctly skips bespoke twins (incl --force); 'nothing to generate' is
correct, not a bug; refreshing a bespoke twin is a deliberate human edit;
accidental drift is the divergence gate's job (age-odv).
Documents the contract in AGENTS-CODEX.md + the codex-sync.sh header so the
confusion that spawned this bead can't recur. Doc/comment only — no logic change.
Closes age-0js4.
--check now verifies each parity twin EXACTLY matches generator output
(presence + registration + byte-identical SKILL.md + prompt.md + mirrored
references), not just presence. This is the single drift gate that lets the
content validators skip parity twins.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The remaining 6 of the original 14 ref-dropping pointers legitimately document
NON-Codex runtimes, so the "0 Claude mentions" twin rule was wrong for them
(scrubbing "Claude" would gut the content). Adds a shared exemption list,
scripts/lint/codex-cross-runtime-skills.txt, honored by the generator AND the
gates:
- codex-sync: for listed skills, apply only the slash->$ rewrite; preserve
runtime names/paths verbatim (Claude Code / ~/.claude stay accurate).
- validate-codex-runtime-sections: skip the no-Claude-mention scan for them.
- audit-codex-parity: skip CLAUDE_TOOL_NAMING for them.
Converts all 6 to self-contained (body + references now ship to Codex):
cass (parses Claude/Codex/Gemini logs), rch (Claude Code PreToolUse hook),
vibing-with-ntm (claude -p LAW-0 ban), agent-native (per-runtime paths),
cc-hooks (Claude Code hook system), agy-native (AGY/Gemini harness).
This completes age-8wm: all 14 pointer twins now self-contained. The 8 ordinary
ones convert clean (Codex-native); these 6 stay runtime-accurate via the
exemption. shellcheck clean; the 3 codex gates pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds --force to codex-sync (scoped regenerate of existing twins; refuses
unscoped to protect the curated set) and fixes two transform bugs found in
review: the slash->$ regex was corrupting markdown PATHS (../foo/ -> ..$foo/),
and only references/scripts were copied (missing fixtures/ etc., breaking body
links). Now mirrors ALL source content except SKILL.md; catalog entries are
add-only so curated reasons aren't clobbered.
Converted 8 pointer twins to self-contained (body transformed runtime-native +
full references/scripts/fixtures mirrored) so Codex users get the real content
(installs ship skills-codex/ only): agent-mail, beads-br, beads-bv,
beads-workflow, dcg, ntm, reverse-engineer, toil-mining.
The other 6 of the original 14 are NOT auto-convertible — their docs legitimately
reference Claude tools/runtime, which the repo's own gates reject in a Codex doc:
cass + rch (Claude tool-naming "the Read tool"/"Bash tool" in references, fails
audit-codex-parity); cc-hooks, vibing-with-ntm, agy-native, agent-native (claude
-p / "the Claude path" etc., fails validate-codex-runtime-sections). They need a
manual Claude-term scrub (or bespoke classification) — tracked on age-8wm.
regen-all --check GREEN; acceptance test 15/15; shellcheck -S warning clean.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Research (this session) established the runtime model: Codex installs ship
skills-codex/ ONLY (plugin.json "skills":"./skills-codex"; install-codex-plugin.sh
copies only skills-codex; install-codex.sh discards the source tarball). So a
pointer twin ("read skills/<name>/SKILL.md") dangles for real users — the twin
must be self-contained (AGENTS-CODEX.md).
codex-sync now generates a self-contained twin from source:
- SKILL.md = slim (name+description) frontmatter + source body transformed
runtime-native: /<known-skill> -> $<known-skill>, ~/.claude -> ~/.codex,
"Claude Code" -> "Codex".
- references/ + scripts/ copied byte-identical (lint scans only SKILL.md).
- Still missing-twin-only + idempotent; existing hand-tended twins untouched
(converting all ~75 is a separate reviewed step; the 14 ref-dropping pointer
twins tracked in age-8wm).
Acceptance test upgraded to assert self-containment: throwaway source skill WITH
a reference + transform cases -> twin carries body + reference, transforms
applied, content-divergence gate passes (15/15). shellcheck -S warning clean.
regen-all docs reconciled (pointer -> self-contained).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
scripts/codex-sync.sh authors the COMPLETE Codex twin for any source skill that
lacks one: a slim (name+description) frontmatter + a fixed pointer body naming
skills/<name>/SKILL.md as the source of truth, the prompt.md pointer template,
the per-skill marker, and all catalog surfaces, then fixes hashes. Because a
parity twin carries no source content beyond name+description, source body edits
never require a twin hand-edit — the divergence/parity/manifest/hash cascade that
made adding a skill cost ~5 serial codex-gate fixes is gone.
- Idempotent + append-only (no catalog re-sort → minimal diffs).
- bespoke twins are the opt-out: never generated or overwritten.
- Wired into regen-all.sh (generate step + --check drift step); stale
"twins are MANUAL" note replaced.
- tests/scripts/test-codex-sync-generator.sh: self-cleaning L2 acceptance —
throwaway source skill → generate → lint-clean, registered twin, gates pass,
zero hand-edits (10/10).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
boshu