skills

Imported from tommimarkus/skills (AGENTS.md). Install upstream with npx skills add tommimarkus/skills. Copyright stays with the author.

AGENTS.md

This repository is a cross-runtime plugin marketplace for Claude Code and Codex, with a native GitHub™ Copilot CLI adapter where a plugin declares one. It publishes the same skills through runtime-specific packaging; the shared skill workflow under each plugin's skills/ directory is the source of truth.

Start here

Before planning, editing, reviewing, or validating a skill, manifest, marketplace, agent wrapper, hook, bundled reference, extension, or helper, read docs/skill-architecture.md. Read the affected skill's own SKILL.md and only the references or extensions its load map selects.

Architecture Review preserves original package evidence. When a reproducibility build is needed, use the architecture skill's isolated-review procedure and its byte-accounted persistent copy; never rebuild or refresh the reviewed original.

Keep this file, CLAUDE.md, and README.md current when repository structure, runtime support, install commands, validation, or a public skill contract changes. AGENTS.md owns Codex-facing repository guidance; CLAUDE.md remains the self-contained Claude Code contract. Cross-runtime rules must agree without making either runtime load the other's file first.

Repository shape

• .agents/plugins/marketplace.json: native Codex marketplace.
• .claude-plugin/marketplace.json: Claude Code marketplace.
• <plugin>/plugin.json + <plugin>/mcp.json: Agent Plugins 1.0.0 manifest and its MCP configuration — the current Codex lane, and the only one that interpolates ${PLUGIN_DATA} in MCP config. The same root plugin.json is the native Copilot manifest when that plugin supports Copilot CLI directly; spec-aware Copilot reads root mcp.json, while its legacy adapter lives at <plugin>/mcp/copilot.mcp.json.
• <plugin>/.codex-plugin/plugin.json: legacy Codex manifest, retained as the fallback lane.
• <plugin>/mcp/codex.mcp.json: legacy Codex MCP adapter when that manifest declares mcpServers.
• <plugin>/.claude-plugin/plugin.json: Claude manifest.
• <plugin>/skills/<skill>/SKILL.md: shared runtime-neutral workflow.
• <plugin>/skills/<skill>/extensions/: on-demand supporting packs; a stack core may own nested mode lanes such as build.md and review.md when the skill's load map declares them.
• <plugin>/agents/<skill>.md: Claude-only subagent wrapper.
• .agents/skills/<name>/SKILL.md: Codex wrapper for a repo-internal skill.
• .claude/skills/<name>/SKILL.md: Claude wrapper for a repo-internal skill.
• internal-skills/<name>/SKILL.md: source of truth for repo-internal skills.
• .codex/hooks.json and .claude/settings.json: runtime hook registration; both invoke shared scripts under scripts/agent-hooks/.

Do not copy a published skill to make it runtime-specific. Put portable workflow in skills/**; isolate host metadata, hook configuration, MCP launch variables, and UI presentation in the host adapter.

Dediren MCP adapter contract

The architecture plugin's Dediren configuration is host-specific, while its shared launcher/router has no harness detection. The maintained host adapters are Claude Code, Codex, and Copilot CLI; the router only launches a local stdio Dediren process for the explicit workspaceRoot supplied to each tool call. Dediren itself is provisioned by the plugin: on first use the launcher installs the pinned, checksum-verified release (pin 2026.10.0, support floor 2026.07.28, overridable by a CalVer DEDIREN_VERSION at or above that floor) into the host's own per-plugin writable data directory. That directory resolves from DEDIREN_HOME (which must be absolute), else CLAUDE_PLUGIN_DATA, COPILOT_PLUGIN_DATA, or PLUGIN_DATA with /dediren appended; there is no invented fallback, so a host offering none exits 78 naming DEDIREN_HOME. Executables resolve in order: an explicit DEDIREN_COMMAND (honoured without a floor probe — the deliberate lane for pinning one executable for controlled validation), the managed install, a host dediren on PATH that reports at or above the floor, the legacy verified-release-cache migration lane, then provisioning the pin. Java stays host-managed and is never downloaded: the release ships jars with no bundled JRE, so Java 21+ is a host prerequisite. The bundled procedure at souroldgeezer-architecture/skills/architecture-design/references/procedures/dediren-install.md is the single place that documents what provisioning does, how to override it, how to run air-gapped, and how to diagnose a failure.

Dediren 2026.08.3 adds export-result.schema.v2 assurance to direct UML/XMI exports. Native package-build results do not surface it, so shared guidance preserves the artifact/source and diagnostic evidence path with an explicit assurance limit.

Dediren 2026.08.4 moves online export-schema fetching into a bounded Java HTTP client, so exports no longer require curl; the plugin launcher may still use curl or wget as a fallback for release downloads. Its additive inline import and negotiated MCP image fields flow through the live discovered schema and unchanged tool result rather than a runtime-specific adapter fork.

Dediren 2026.08.6 adds the non-failing DEDIREN_RENDER_EDGE_LABEL_OCCLUDED warning when the renderer cannot place an edge label without occluding content. A render carrying it still returns its SVG, but architecture review maps the affected view to ARCH-R-3 until the label is made visually clear or the limitation is disclosed.

Dediren 2026.08.7 adds a draw.io® import lane: dediren_import accepts a third plugin id, drawio, beside mermaid and dot. An imported draw.io file always lands as generic-graph (generic.node / generic.link) rather than a promoted model, because draw.io carries relationship semantics only as arrowhead decoration, and the non-failing DEDIREN_DRAWIO_HINT_IGNORED warning names the geometry and presentation keys ELK re-lays out. The release's draw.io export engine is reachable from no build driver, so the tool set stays at eight and the skill's trigger boundary still excludes diagrams the user wants kept in that format.

Dediren 2026.08.8 adds an ascii render engine — box-drawn text diagrams from the same layout stages, Unicode by default with a plain-ASCII text.charset option — reachable only from the standalone render stage and a fourth dediren_import output mode, text, which returns an inline text diagram as a second text content beside the imported envelope. No build driver selects it, so the tool set stays at eight and SVG remains the evidence of record. Render policies move to render-policy.schema.v4: the runtime refuses a v3 policy with a single-operation set_version migration diagnostic, so checked-in packages migrate that one field. Dediren 2026.08.9 converges render-result artifact_kind onto the media-suffix form (v7): svg → svg+xml and text → ascii+text, breaking for consumers reading that field. The repo's fixture compatibility baseline moves to 2026.08.9; the support floor stays 2026.07.28.

Dediren 2026.09.0 emits layout-result.schema.v3: edges carry a typed route (polyline or cubic Bezier) instead of top-level points. Regenerate stored layouts and migrate consumers; there is no v2 output fallback. Authored models and render policies remain compatible, so the fixture baseline stays 2026.08.9 and the support floor stays 2026.07.28.

The shared root mcp.json therefore declares no env and no cwd: one host would expand a token there and the other would not. Both export the plugin data directory into the child, which is what the resolver reads.

Codex's 30s startup default is safe: the router answers initialize itself without touching Dediren, and provisioning happens later, on the first tools/list.

Generic local-client compatibility means only that a local client can launch a stdio process and permits Bash, Python, and Java 21+ with a writable plugin data directory; it must set DEDIREN_HOME to an absolute path when it offers no plugin data variable, may optionally set DEDIREN_COMMAND instead, and must pass an absolute workspaceRoot on every tool call. It is not a support or packaging promise for another harness. Preserve the legacy verified-release-cache fallback; nothing populates it any more. Streamable HTTP is future work only for an explicit remote/shared multi-client service requirement, because it adds authentication, origin validation, port and service lifecycle, session isolation, and workspace authorization responsibilities.

Required conventions

• git-workflow-policy: feature branches, persistent repo-local worktrees, clean worktree, no direct main.
• Create every task worktree under the primary checkout's gitignored, persistent .worktrees/<task-name>/ directory. Never place a Git worktree or uncommitted task work under /tmp, $TMPDIR, /var/tmp, a tmpfs/ramdisk, or another ephemeral location, even for a short-lived task. Gitignored does not mean disposable. Run worktree creation from the primary checkout; if its .worktrees/ is unavailable, stop and ask before choosing a different persistent location.
• Use jq for JSON and Mike Farah yq for YAML frontmatter, TOML, and XML.
• Use rg or rg --files for repository search.
• Preserve the existing Python 3.11 floor and repo-local uv configuration.
• Lean Audit's metadata-only workflow_cost.py --trace lane streams native Codex rollout JSONL, sums complete last_token_usage records rather than cumulative totals, and reports explicit coverage plus bounded content-free lifecycle counters. Missing or partial usage is calibration-ineligible; the counters are evidence, not automatic causal findings or proof of livelock.
• Lean Audit normal Markdown scans report requested-scope coverage and reject an empty eligible scope; workflow forecasts require declared core evidence before reporting feasible or at-risk, while a proved expected overflow remains a block.
• Do not force-add ignored files. Before a commit, run git ls-files -ci --exclude-standard; the result must be empty unless the user explicitly approved an exact tracked exception.
• Run repository-wide scanners from the clean task worktree itself, not the primary checkout; nested worktrees otherwise pollute primary enumeration.
• Shared skill commands must preserve documented Claude substitutions and add a Codex source-path form beside them. Never replace ${CLAUDE_SKILL_DIR} or ${CLAUDE_PLUGIN_ROOT} with a generic placeholder as the only instruction.
• data-efficiency.md is shared: api-design owns its HTTP-to-storage application and API findings; software-design owns non-HTTP algorithms and data paths. Report each defect once.
• Codex hook commands use ${PLUGIN_ROOT} / ${PLUGIN_DATA}. Codex MCP interpolation depends on the lane: the Agent Plugins root mcp.json interpolates ${PLUGIN_ROOT} / ${PLUGIN_DATA}, so it is the only Codex lane that can hand a server a writable plugin data root; the legacy .codex-plugin + mcp/codex.mcp.json fields stay literal — use plugin-relative cwd / paths where changing directory is correct, or a tested source-discovery bootstrap when the server must preserve the caller's workspace, and expect no plugin data root there. Claude MCP and hook commands use ${CLAUDE_PLUGIN_ROOT} / ${CLAUDE_PLUGIN_DATA}.
• Legacy Copilot MCP commands use ${PLUGIN_ROOT} and writable plugin data uses ${COPILOT_PLUGIN_DATA}. Keep that separate fallback file; never let legacy Copilot fall through to the Codex bootstrap. Spec-aware Copilot consumes the shared root mcp.json instead and exports plugin-data variables to the child; keep that root file free of env and cwd, as documented above.

Inspect existing tests before selecting the RED test, and classify the change first: new or changed observable behavior needs a focused failing test at the cheapest level that proves it; a behavior-preserving refactor runs under existing passing tests, adding bounded characterization coverage only where protection is missing. Extend a suitable cohesive scenario without weakening coverage; create a new test when the scenario is distinct or reuse would weaken clarity or regression coverage, reusing existing fixtures. A pre-existing failure counts as RED only when it precisely represents the intended behavior. Run the focused scenario per RED/GREEN step and the full suite at the declared cadence. REFACTOR includes the suite: retire or consolidate a test the new one supersedes, naming its successor. Reuse tests/surface_test_lib.py helpers before defining new ones; share only immutable setup; no fixed sleeps, real clocks, or reliance on the machine's locale or timezone.

Runtime parity

Every published plugin appears in both marketplaces and has both manifests. Keep plugin sets, ordering, names, descriptions, and semantic versions aligned. The Claude manifest and README preserve CalVer YYYY.0M.MICRO; Codex derives strict SemVer YYYY.M.MICRO from that authority. Marketplace entries never carry a version field.

When a plugin has a root plugin.json (the Agent Plugins manifest, also read by Copilot CLI), keep its name, description, skills path, and strict-SemVer version aligned with the legacy Codex manifest.

Each public SKILL.md keeps its matching Claude subagent. Codex discovers the same skill through the Codex manifest's skills path; do not create a parallel Codex workflow. Each internal-skills/<name> entry has thin wrappers under both .agents/skills/<name> and .claude/skills/<name>.

Keep stack composition explicit in the shared load map: app-design loads Vite before React for Vite + React, retains React before Next.js, and permits Vite alone. JavaScript/TypeScript software guidance remains the existing typescript.md lane; security uses its separate evidence-gated jsts.* pack, and Node/React lifecycle-test rules remain under test-quality-audit. App-design also owns user-flow mapping and adaptive screen layout through a framework-neutral on-demand procedure for substantial multi-screen, dashboard, and material-layout work. Approved direction skips alternatives; only routine component/state work and narrow approved-layout changes skip the whole procedure. Unsettled direction calls for two or three meaningful alternatives with tradeoffs and a selection checkpoint. Modal dialogs have modality semantics distinct from nonmodal popovers, tooltips, and portal mounting. Supported 'use server' Server Function references may cross the Server/Client prop boundary; ordinary functions, server-only clients, and secrets may not. Every Deep test-quality audit assesses suite health by establishing management evidence before sampling: feedback lanes, project-declared budgets, current results, runtime distribution, reliability, ownership, overlap, and retirement discipline. It also includes a bounded setup/teardown lifecycle assessment for cost attribution, safe infrastructure amortization, per-test mutable-state isolation, and failure-safe cleanup. Deep appends a propose-only suite recovery program when Suite health substantiates a feedback or efficiency finding. Quick remains per-test. Missing optional history or effectiveness evidence is unknown, not a prompt to build analytics.

When a shared workflow needs host behavior, state the capability and give a runtime mapping with a safe fallback. For example, Claude planning retains EnterPlanMode / ExitPlanMode; Codex uses Plan mode when exposed and otherwise emits a proposed plan for explicit approval.

For every operation that crosses about one second, keep status discoverable. Immediately acknowledge known slow foreground work, then report meaningful milestones or confirmed waiting within 60 seconds when the host can emit them. Use real completed/total progress only when a total is known; otherwise label the state indeterminate and never invent a percentage or ETA. Clear busy status on usable success, failure, cancellation, or awaiting input; keep housekeeping and terminal outcomes inspectable, with actionable failures surfaced. Prefer host notifications over polling and aggregate background status without repeated interruption. Do not promise an update during an uninterruptible host call; disclose that limit when it applies. The timing limits are repository guidance, not a host guarantee.

Bounded audit-lane gate

The shared audit craft contract defines a bounded-lane gate: Quick gate: <status> for test-quality and DevSecOps, triage gate: <status> for IP, and limited-scope gate: <status> for bounded Lean. Its status is fail for a substantiated in-scope block, otherwise not-evaluated when required evidence or machinery cannot rule out blockers, otherwise pass-limited. This is a mechanical limited-scope check, not a Deep/in-depth/full-repo rollup or reasonable-assurance verdict; see audit-craft.md §4a. IP findings retain their coded criterion, authority class, fact/inference, remediation, and counsel outcome; neither gate nor verdict is legal clearance.

software-design also owns an early-return File Edit lane for bounded non-code text/data changes with no software-design or sibling-owned decision. It does not expand into source-code, API/schema redesign, IaC, or ambiguous destructive work: use the shared workflow's format-aware precedence and direct validation. Its optional clone-local native-tool state helper emits bounded JSON (tool_state.py list / tool_state.py gc) and is advisory only.

For DevSecOps audits, resolve cost guidance from the target repository's AGENTS.md and CLAUDE.md regardless of the active harness. Apply the rule scoped to the current host and task; retain matching guidance from the other file as evidence and disclose conflicting policies before applying paid-control criteria. Do not treat this repository's guidance as the target's policy.

Planning-policy execution contract (Codex)

Refine plan prose for a fresh parent at Codex sol/high, Claude opus/high, or comparable capability on another host, following orchestrator readability. This writing target carries decisions across a context reset; it does not set runtime models or change subagent tier selection.

Executable approval transport uses planning-approval-handoff-v1: a canonical plan_sha256 plus exactly one absolute persistent plan_path or complete inline v5 plan. Before approval, emit and resolve the envelope and include it inside the host-carried plan; resolve again before capability binding and dispatch. Prefer the primary checkout's ignored .planning-policy/plans when saving is explicitly permitted, or use an explicitly supplied durable root; retain the older <git-common-dir>/planning-policy/plans/<sha256>/plan.json only for reference/recovery. Use python3 -B persist_plan.py --plan-root ABSOLUTE_ROOT PLAN. The writer validates and atomically publishes canonical bytes without overwrite; the validator/resolver helper remains read-only. Use inline JSON without probing when writes or an eligible root are unavailable. Parent recovery may inspect only the bounded same-task evidence described in approval handoff; workers still stop for missing assignment fields. Prose summaries never replace canonical execution JSON.

Generated worker transport uses planning-worker-handoff-v1: the read-only planning_ledger.py handoff command carries shared approved decisions, exact leaf/work-unit and current assignment, binding, and return schema. Workers use read-only validate-return before parent ingestion; record-return still owns current-attempt validation. New v5 admission rejects unsafe/nonstring IO paths, placeholder decisions, known no-op acceptance, and unordered shared owners or overlapping writes across work units. Retained ledgers preserve prior admission behavior. See worker handoff.

The shared planning-policy contract is runtime-neutral. New executable plans use contract_version: 5. Start them from references/templates/plan-v5.json; the discriminator is contract_version, never version. Versions 1–4 are resume-compatible only: new init-v4 is refused as blocked:contract_migration_required, while existing v4 records remain resumable and mutable; do not initialize new work from a legacy plan or run. Every executable leaf has decision-complete, stable fields: IDs/dependencies, task/boundary, named read/write sets, settled decisions, size, portable tier, worktree owner, one acceptance command, bounded return contract, stop conditions, and stable work unit ID, plus exact capability_requirements: baseline plan-step-base-v1 and bounded additional requirements. Its assigned work unit owns the cohesive_outcome and decomposition evidence: shape: single has only shape; parallel has basis: parallel_independence plus rationale; and checkpointed has basis: failure_isolation or rollback_boundary plus rationale. A missing load-bearing field stops as blocked:missing_input; do not search for or invent it. Work units are weighted once from their original size (small=1, medium=2, large=3) and require standard_ready_ratio >= 0.60; only an explicitly user-approved, recorded analytical-heavy exception waives that gate. After approach convergence, the parent enumerates shared call sites, guidance, named reads/writes, and existing scoped acceptance once. It records bounded worker judgment separately from required missing input; size follows those bounded reads and acceptance, and large names a concrete irreducible reason. Two checks alone never require two leaves. A valid decision-complete v5 plan is approval-ready without host binding; it is dispatch-ready only after planning-capability-binding-v1 joins plan digest, every leaf, host/executor, requirements, and bounded evidence. An unavailable or mismatched join stops blocked:capability_unavailable; never silently substitute or downgrade. Each v5 plan carries an at-most-4-KiB advisory planning-execution-cost-v1 block. The existing validator invocation emits an at-most-600-proxy-token planning-cost-advisory-v1; missing or invalid profiles, unknown ranges, shared-prefix repetition, retry multiplication, and verification reserve never affect validity, readiness, dispatch, retry, or lifecycle. Keep stable-proxy, declared-model-token, and provider-measured lanes separate. Three advisory codes flag planning-cost signals: PLANCOST-UNBATCHED-CHAIN (an unbatched dependency-consecutive same-owner mechanical/standard pair), PLANCOST-PLAN-SCALE (more than 12 leaves or 20 declared work-unit weight), and PLANCOST-MICROLEAF-RISK (merge candidates back into their work unit's cohesive outcome unless its v5 decomposition evidence justifies the split). Groom microleaves first; if the plan remains over the scale signal, slice it into successive plans. Grooming acts on all three signals before approval, never as a validity gate. The human plan has one compact Execution economics summary and tracing: off. Route an initial inspection to at most one owning audit only when its bounded question and evidence surface remain unresolved by targeted inspection or focused tests; ordinary design is not an audit route.

A leaf's acceptance command is scoped to its own write set; a whole-suite run belongs only to the parent's final verification, run once at closeout, never per integration cycle. A leaf may also declare a batch: 2 to 8 chained mechanical/standard leaves sharing one worktree owner dispatch once, in leaves-array order, in that one shared worktree, with one bounded return per member. An in-batch dependency on an earlier-listed member satisfies readiness at ready/in_progress/completed; an external dependency needs integrated or cleaned (a v5 run; earlier versions need cleaned). When a member stops, transition --to pending unwinds its never-run followers — refunding the attempt and clearing agent/attempt identity — the stopped member remediates in the same worktree, and unwound followers redispatch as singles. The batch integrates once, via the helper's --batch-commit entries, only once every member is completed or terminal. A per-integration rebased_tree_changed: false keeps a leaf's recorded acceptance; true re-runs only that leaf's scoped acceptance.

The parent starts a leaf, or a whole batch, with the composite dispatch: it checks that the assigned worktree is registered on the leaf's worktree_owner (its git branch name) before any state change, creating it with --create-from, then readies, starts, and returns one worker packet per member. The granular transition and handoff commands remain for recovery.

For an approved plan with at least two delegated steps, only the parent may activate and write a run at <git-common-dir>/planning-policy/ledgers/<plan-id>/<run-id>/; run-id is a lowercase UUID4. The parent assigns every declared step exactly once and issues one current opaque attempt ID for it. Agents may concurrently execute only independent ready steps with separate worktrees and write paths. A step has a finite max_attempts (1–5): identical progress fingerprints block a retry as blocked:no_progress; an exhausted step is terminal blocked:retry_exhausted; and a boundary overrun is terminal oversized, never an expanded retry. The ledger is the sole retry-policy owner: new v5 runs stamp retry_policy: escalating_remediation_v1; policy-less v2/v3 and v1 preserve old behavior. portable_tier is initial only. One predicate classifies a return by its first blocker in its status family. Reasoning stops are eligible; one same-tier retry is allowed only after failed:acceptance, while blocked:needs_higher_tier escalates immediately. Later retries use higher tiers through deep/max_attempts. Repairable stops (blocked:environment, or another blocked/failed stop amended after its return) retry at the same tier without spending that retry or escalating. Each retry persists a bounded retry-remediation-v1 artifact and checks identity, prior-return digest, worktree, boundary, and assignment. Terminal precedence is repeated result (blocked:no_progress), ineligible outcome, exhaustion (blocked:retry_exhausted), then tier ceiling.

The parent may amend an active v5 step's execution metadata only: add write/read paths, replace acceptance_command, or raise max_attempts (at most 5). The bounded per-step overlay and its amend-v5 event leave plan.json, the plan hash, and capability bindings unchanged, and one effective leaf feeds return validation, packets, and step validation. Task, boundary, decisions, dependencies, tier, and owner still need a new approved plan.

Every successful v5 lifecycle result carries a live next block of at most 120 proxy tokens. After a long pause or context compaction, read-only show --next-only returns one highest-priority action in an at-most-240-token envelope. Full show remains the diagnostic fallback; load the ledger runtime reference only for errors, legacy resumption, diagnosis, retention operations, or ledger authoring/audit. Between active returns, wait for a host notification; never busy-poll or start an autonomous lifecycle loop.

Successful v2/v3/v4/v5 steps continue completed → integrated → cleaned. The parent ingests bounded planning-worktree-result-v1 evidence from the Git-policy helper: rebase the exact returned branch onto the current parent, fast-forward-only merge, then prove merged ancestry and clean up without force. Cleanup retries safely after partial removal by revalidating recorded identity, branch state, and target ancestry. Routine integration never cherry-picks. In v5 the parent's land runs the helper's integrate then cleanup and records both; a cleanup failure leaves the step integrated, and a batch lands once. Dependencies become ready once their prerequisites are integrated (v5; earlier versions need cleaned), and their worktrees start at the then-current parent tip. validate --closeout requires every successful step to be cleaned.

Use bounded checkpoint and lifecycle/retry returns, never raw logs. Every delegated handoff is one at-most-8-KiB bounded-step-return-v1 JSON object; it carries its step/agent/attempt identity, bounded result facts, and no run_id. The ledger hashes its canonical approved plan; a mismatch is blocked:plan_tampered. Its bounded show rehydrates one step or a truncated run summary, not history. Version-1 ledgers remain readable and mutable in place with retry_policy: legacy_unbounded until every version-1 ledger is terminal. Version-1 keeps its terminal integrated state and does not gain cleaned. Current planning-policy cannot approve or dispatch an unversioned version-1 plan as new work; new documentation uses init-v5. Versions 1–4 remain resume-compatible only. Remove legacy support only in a later explicit breaking release after no version-1 ledger is nonterminal. The parent owns integration and end-to-end verification; a delegated return covers only its assigned drafting and acceptance check.

The parent closes a version-2/3/4/5 run with explicit completed, blocked, or abandoned outcome, reopens only an eligible retained blocked run, and uses list for bounded discovery. gc --dry-run previews conservative retention: completed runs 30 days, blocked runs 90 days, abandoned runs 7 days; active, invalid, and ambiguous records remain preserved. purge --actor parent targets one closed run only (and needs --before-retention plus reason before expiry); there is no bulk deletion.

Runtime tracing is a separate explicit opt-in per v3/v4/v5 run. Ordinary planning and execution create no usage directory, inspect no telemetry, install no hooks, and make no network or provider call. Only an explicit request to trace, measure, or calibrate loads the trace-init, trace-record, trace-show, and trace-close procedure. Usage records contain bounded counters plus harness/model provenance, never prompts, completions, arguments, results, or raw logs; they live outside the checkpoint and follow run retention/purge.

Codex maps the portable tiers exactly: mechanical → gpt-5.6-luna/low, standard → gpt-5.6-terra/medium, analytical → gpt-5.6-sol/high, and deep → gpt-5.6-sol/xhigh. If the selected mapping is unavailable, return blocked:model_unavailable with the requested tier/model/effort and availability evidence; never silently downgrade. The opt-in fresh-context evidence command is uv run python scripts/planning_policy_forward_eval.py --harness both --output-dir /secure/path --execute; it writes bounded comparison summaries only.

A v5 plan may carry an optional top-level series block that slices an oversized plan into successive plans: series_id, slice, final, end_verification_commands declared once at slice 1 and copied verbatim forward, and, at slice > 1, a required copied-evidence predecessor block. close --series-handoff-file <path> is required on a completed close of a non-final slice, forbidden on a non-series plan and on the final slice, and optional at blocked/abandoned; the ledger composes the bounded handoff artifact from the closing run's own identity, never caller-supplied. A slice > 1 init-v5 splices one series_predecessor disclosure — matched, a mismatch:<field>, or unresolvable — and a purged or unreadable predecessor never fails the successor's own init. A series-final plan's closeout carries the compact series_end: true marker in place of inlined commands; the parent still runs end_verification_commands itself, exactly like final verification today. Absent series, behavior is byte-identical to today's.

Version and release policy

The Claude manifest and README use CalVer YYYY.0M.MICRO as the release authority. Codex and any native Copilot manifest mirror it as strict SemVer YYYY.M.MICRO.

Feature branches and worktrees carry content only. Do not increment existing version cells there. Verify the exact clean candidate before integration, then fast-forward that commit. After integration, compute the next stamp on main:

uv run python scripts/version_stamp.py guard
uv run python scripts/version_stamp.py compute --plugin <name>

Then apply the padded computed stamp to the Claude manifest and matching README cell, and its normalized derivative to the Codex and native Copilot manifests, in an integration commit that contains only version changes. Verification evidence from the exact clean candidate survives that atomic follow-up only when fast-forward ancestry is proved and the complete change is limited to these version cells: the Claude manifest, the matching normalized legacy Codex and (when present) root Agent Plugins/Copilot manifests, and the matching README version-table cell. Run the focused version and metadata-parity checks for that fixed surface. Any other source, plan, evidence, surface, or integration drift requires the full candidate verification again. New manifests added by a feature branch may carry the existing release's SemVer-normalized value; that is packaging content, not a release increment.

Breaking or additive public-surface work requires the repository's in-depth ip-hygiene gate. Cosmetic changes use scoped triage.

Validation

Run the changed-surface checks first. Before integration, run the following ordered candidate gates from the clean persistent task worktree at repository root, preserving each command's exit status:

python scripts/check-runtime-metadata-parity.py --check .
scripts/validate-fragmentation.sh
scripts/skill-architecture-report.sh --strict .
uv run python -m unittest discover -s tests -p '*_test.py'
scripts/check-runtime-host-smoke.py --fresh --assert-profile-isolation --changed-since main .
git diff --check
uv run python scripts/version_stamp.py guard

Run the version guard after the candidate gates and before fast-forward integration. The fragmentation script runs metadata and stop-hook checks. The explicit *_test.py discovery command above owns the one full-suite run at closeout. This exact clean candidate and ordered gate sequence own the full verification evidence; fast-forward integration preserves it. If only the fixed version cells documented above change afterward, run the focused version guard and metadata-parity checks. Any other drift returns to the full sequence.

Also validate every Codex plugin with the current first-party plugin validator when it is available, and run claude plugin validate --strict through the repository report path when the Claude CLI is installed. A test run that collects zero tests is a failed gate.

Never let a pipeline stage or a || fallback own a gate's reported exit code — cmd | tail or cmd | grep ... || fallback reports the downstream stage's status, not the gate's, and can read green while the gate itself failed. Capture ${PIPESTATUS[0]} right after the pipe, redirect output to a file and test the bare command, or run the gate unpiped; a status that provably came from a downstream stage is no evidence the gate ran or passed.

The host smoke must keep both safety flags. It uses temporary CODEX_HOME, CLAUDE_CONFIG_DIR, COPILOT_HOME, and COPILOT_CACHE_HOME state without replacing HOME, clears inherited plugin-data roots that could redirect provisioning, verifies installed plugin, skill, agent, and Dediren MCP surfaces, and fingerprints the normal host plugin/config control planes before and after. Dediren itself is plugin-provisioned, so the smoke resolves it through the launcher's own lanes — an explicit DEDIREN_COMMAND, or a temporary DEDIREN_HOME that keeps a provisioned bundle out of normal host state — and never installs into a real per-plugin data directory. Absence of a standalone Codex validator is a reported skip, not a fabricated pass.

Documentation and ownership

Update README.md when install commands, plugin names, skills, public behavior, or local validation changes. Update docs/release-checklist.md and docs/maintenance-procedures.md when packaging or version mechanics change. Use docs/contributing.md as the contributor entry point and keep its guide map accurate when a maintained documentation surface moves. Keep .github/CODEOWNERS on executable hook configuration and hook scripts.

No checked-in .codex/config.toml should choose a model, approval policy, or sandbox profile for contributors unless the repository genuinely requires that setting. Repo-local hooks are enough for this repository and remain subject to Codex trust review.