synthesis-agent-conformance v1.9.6A

Immutable. This exact content is served forever at /api/v1/blob/38988bac4d617bbb.

---
name: synthesis-agent-conformance
description: Audit, install, and verify a synthesis ecosystem across multiple AI agent runtimes. Use for Claude Code and OpenAI Codex parity audits, AGENTS.md and CLAUDE.md instruction migrations, skill or plugin deployment checks, lifecycle-hook health, Mac bootstrap validation, active-project handoffs, post-compaction recovery, and any request to make synthesis project management portable between agent clients.
license: "Apache-2.0"
depends_on: ["synthesis-project-management", "synthesis-context-lifecycle"]
metadata:
  author: "Rajiv Pant"
  version: "1.9.6"
  source_repo: "github.com/synthesisengineering/synthesis-skills"
  source_type: "public"
---

# Synthesis Agent Conformance

Treat cross-agent portability as a continuously tested system, not a file-count
comparison.

## Operating model

Verify five planes:

1. **Source:** version-controlled skills, instructions, client adapters, hooks,
   project state, and configuration.
2. **Installed:** deployed plugins and skills, generated files, catalogs,
   instruction budgets, runtime configuration, and Codex's authoritative hook
   trust state. Never infer or write trust state.
3. **Live:** client-specific receipts created by genuine lifecycle events. A
   static script probe is not live evidence.
4. **Continuity:** coordination leases, active pointers, attributed local
   working state, explicit remote publication, and bidirectional handoff
   exercises.
5. **Capability:** authenticated read-only outcomes and explicitly supported,
   unsupported, or unverifiable product surfaces.

Name the plane whenever two facts appear to conflict. Runtime state determines
current behavior; canonical state determines what the next deployment should
produce.

Active and stopped payload parity use diagnostic context rendering: compare
the complete local context, including unread messages, without acknowledging
delivery, writing lifecycle receipts, checking release currency, fetching Git,
fast-forwarding a checkout or refreshing a lease. Unreadable diagnostic inbox
state fails closed. Validation targets the selected seat/project's inbox;
demonstrably unrelated historical blocks cannot redefine its native messages
or delivery keys. These probes establish agreement over local evidence, not
remote freshness or actual client delivery. Other conformance checks may refresh
state; do not describe the entire command as read-only.

Both client renderers and project state use the shared confined controlling-plan
resolver. Structured authority precedes historical prose, parent-plan hashes
invalidate stale checkpoints, and stopped comparisons remap the plan into the
causally selected worktree. Missing, malformed and ambiguous legacy references
remain non-green; diagnostic rendering does not rewrite history to resolve them.

## Workflow

### 1. Inventory

Run:

```bash
python3 scripts/conformance.py source
python3 scripts/conformance.py runtime
python3 scripts/conformance.py parity
python3 scripts/conformance.py catalog
python3 scripts/conformance.py instructions --repo-root <repo>
python3 scripts/conformance.py instruction-budget --repo-root <repo>
python3 scripts/conformance.py hook-definition
python3 scripts/conformance.py hook-trust --repo-root <repo>
python3 scripts/conformance.py hook-live
python3 scripts/conformance.py coordination
python3 scripts/conformance.py capabilities --repo-root <repo>
python3 scripts/conformance.py surfaces
```

`hook-live` without selectors answers the current-health question: it checks
the newest Claude and Codex receipt pointers and keeps the 24-hour freshness
gate. To reverify a release or handoff against its exact accepted sessions,
select the preserved event records explicitly:

```bash
python3 scripts/conformance.py hook-live \
  --claude-receipt-session-id <claude-session-uuid> \
  --codex-receipt-session-id <codex-session-uuid>
```

Do not substitute one scope for the other. A newer unrelated start may make
current health fail without erasing an earlier accepted event; an accepted
session check does not establish that the newest global start is healthy.
Preserved events are local runtime evidence and have no automatic age-based
deletion. Exact-session checks waive only the 24-hour freshness limit; they
still require the original client-owned transcript, matching session UUID,
plugin version, and exact plugin root to validate.

Transcript identity validation scans the first 1,000 physical JSONL lines,
validates complete records within that window, and retains only bounded
identity fields. Long histories and large message strings do not require
whole-file or whole-record allocation. Malformed records, conflicting identity,
duplicate identity keys and excessive nesting fail closed. This is a bounded
startup-identity check, not a claim that every later transcript record was
semantically validated. Onboarding separately streams the full-file digest.

Use `--json` for a machine-readable report. Each check carries a plane and one
of PASS, FAIL, WARN, UNKNOWN, or UNSUPPORTED. A required UNKNOWN fails the
aggregate command; "not tested" cannot become parity.

### 2. Repair from source

- Edit source repositories, never installed skill or plugin caches.
- Keep shared behavior agent-neutral.
- Use native adapters for platform differences.
- Make `AGENTS.md` canonical for tracked repository instructions.
- Make `CLAUDE.md` a small documented import adapter: `@AGENTS.md`.
- Install public skills as the `synthesis-skills` plugin on Claude and Codex.
- Install private skills to `~/.claude/skills` and `~/.agents/skills`.
- Do not create a second source-managed copy under `~/.codex/skills`.

### 3. Activate durable project state

When starting or switching a synthesis project:

```bash
python3 scripts/conformance.py activate \
  --project <project-directory> \
  --session-id <coordination-session-id>
```

The command writes a local pointer only. `CONTEXT.md`, `REFERENCE.md`,
`sessions/`, and plan artifacts remain the source of truth. The pointer records
the owning session and coordination-board lease URL, plus its worktree,
branch, and source commit; `pointer` verifies those fields against disk.
Activation and pointer validation share the local-continuity record contract:
uncommitted project edits are acceptable exactly when session-attributed
pending manifests record every dirty path, and any unattributed path fails
closed. A live owner holding an attributed stopped-task record
(`LOCAL_READY` or `LOCAL_RECOVERABLE`) can therefore activate without
committing first.

Before activation writes, read and claim the source areas on
`~/.synthesis/coordination/active-sessions.md`. Conformance validates the board
shape; `synthesis-project-management` owns its operating protocol.

### 4. Verify handoff

Run:

```bash
python3 scripts/conformance.py handoff --project <project-directory>
python3 scripts/conformance.py pointer --project <project-directory>
python3 scripts/conformance.py continuity \
  --project <project-directory> --readiness local
python3 scripts/conformance.py continuity \
  --project <project-directory> --readiness remote
```

`pointer` verifies a live owner's leased cache. Local continuity verifies that
Claude and Codex reconstruct identical project state with no pointer. A clean,
readable record with no attributed task edits is `LOCAL_READY` without creating
empty evidence. When a task changes repository files, a current Stop receipt is
required for `LOCAL_READY`; the attributed manifest without that receipt is
`LOCAL_RECOVERABLE` after interruption. Remote continuity additionally requires
no pending manifest and complete branch-head equality with the fetched upstream,
not merely equality for commits touching the project subdirectory. Then open
the project in the other client and confirm its SessionStart or first
named-project turn recovers the same state.

The aggregate `all` command treats a readable active pointer owned by another
project as non-blocking diagnostic context and verifies stopped-project
recovery instead. The explicit `pointer` command remains strict for whichever
project the caller asks it to validate; malformed pointers fail in both modes. The SessionStart hook records its live receipt before it builds context, and a pointer it cannot validate is ignored with a notice rather than failing the session: a pointer is another session's cache, never authority for the one starting.

The continuity plane also runs causal project-state recovery. It enumerates
every registered worktree and ref plus attributed manifests, receipts, pointer,
and claims; selects only by equality or ancestry; and reports `CONFLICT` or
`UNKNOWN` separately from a successful local recovery. Source, installed,
live, continuity, and capability verdicts remain independent—a matching cache
cannot compensate for a stale loaded registry, and an unavailable remote
cannot become a green continuity result.

### 5. Close the loop

Run the complete check:

```bash
python3 scripts/conformance.py all \
  --repo-root <current-repo> \
  --project <project-directory>
```

Fix every failed required check. Record genuine client-owned differences as
boundaries with evidence; do not report parity from matching inventories alone.
Since 1.7.0 parity also reads each client's installed manifest on disk beside
the CLI report (`parity.<client>-on-disk`): a self-report is a claim, not
evidence — it once stayed green while the loaded tree sat three releases behind.

## Lifecycle hooks

The plugin’s `hooks/hooks.json` uses `session_context.py` at `SessionStart`.
Codex reruns `SessionStart` after root-session compaction with a `compact` start
source, so the same hook restores the active project without a second
behavior-producing implementation. The script:

- verifies the local clock;
- reads the active-project pointer;
- discovers a stopped project directly when the task directory is inside its
  durable project tree;
- when the task starts at a workspace or knowledge-repository root without a
  pointer, boundedly audits the immediately discoverable Git-tracked project
  registries and warns if a canonical checkout is behind its fetched upstream
  or if registry freshness is not comparable;
- when neither route identifies a project, instructs the receiving agent to
  resolve the user's named project through the git-tracked registry and run
  the Session Start Protocol automatically;
- verifies that the project still exists;
- extracts the current phase, status, plan, and next actions from durable files;
- emits a compact context anchor;
- appends an immutable event record for every genuine `SessionStart`, then
  advances atomic generic and client-specific latest pointers monotonically.
  Exact-session conformance reads the event registry, so a later unrelated
  start cannot erase the addressability of accepted evidence. Claude may name its
  client-owned transcript before creating its first JSONL record; the receipt
  preserves that lifecycle event and records whether the binding existed at
  hook time. Release conformance still requires the exact transcript to bind
  the same session UUID. Claude evidence must use the canonical
  `projects/<encoded-cwd>/<session-id>.jsonl` root shape; subagent descendants,
  symlinks, and contradictory UUID declarations fail closed. Current-health
  checks still require the latest public-plugin receipts from both Claude Code
  and Codex. Release and handoff reverification must select the exact durable
  session UUIDs rather than trusting whichever global receipt happens to be
  newest. The private Codex control-plane receipt remains a separate opt-in
  check.

Claude calls the same script from its native `SessionStart` hook. Client hook
configuration remains an adapter; the context-producing behavior is shared.
Codex hook trust is a separate human-controlled check within installed state:
`hook-trust` queries
Codex app-server's read-only `hooks/list` API for the current normalized hash,
source owner, and trust reason, and never edits `hooks.state`.

The active pointer is deliberately not synchronized as one global current
project. Parallel root sessions may work on different projects. Same-machine
cross-client continuity consumes project files plus attributed working-tree
state. Cross-computer continuity requires the explicit `REMOTE_READY`
transition and a fast-forwarded destination checkout.

## Skill catalog contract

Codex budgets the combined model-visible skill catalog at 2% of the active
model context. Audit the resolved catalog through app-server `skills/list`;
do not infer safety from the public plugin's file count. Public specialist
skills may set `policy.allow_implicit_invocation: false` in
`agents/openai.yaml`: they remain enabled and explicitly invocable, while
`synthesis-skill-router` supplies natural-language routing. Claude Code ignores
that OpenAI-specific prompt policy and retains its native trigger behavior.

## Detailed architecture

Read [references/architecture.md](references/architecture.md) when designing or
changing an installation, plugin package, hook set, or cross-machine sync.

## Instruction-kernel pattern

Read [references/instruction-kernel-pattern.md](references/instruction-kernel-pattern.md)
when an always-loaded instruction file approaches its budget or rules migrate
to skill, hook, or config homes: the thin-kernel structure, the four
enforcement classes, the not-weakening proof obligation, and the budget gate.