spec-audit

name	spec-audit
description	Map and verify the CTS/schema documentation corpus against its normative contracts, implementation, tests, fixtures, and runtime consumers. Use for claim-level audits or updates in docs/specs/ts-transformer, docs/specs/schema-generator, package guidance, and author-facing CTS docs, especially after transformer/schema changes or before releases.

Spec audit: docs vs code for the CTS compiler surface

Why this exists

The 2026-07 audit found the current-behavior spec denying an implemented, fixture-pinned CFC ifc.* lowering subsystem. Use this map to distinguish normative disagreement from descriptive drift and to find the repository's load-bearing evidence quickly.

The map

• Start at docs/specs/ts-transformer/README.md for the corpus and each document's authority. Normative target-language/lowering contracts win over code; descriptive current-behavior and schema-mapping specs follow code and passing tests.
• Ground implementation claims in the relevant canonical constant or source, targeted tests, and—where output shape matters—the packages/ts-transformers/test/fixtures/** input/expected corpus. Inspect live emission with deno task cf check <file> --show-transformed --no-run.
• Canonical constants the specs cite (spot-check the citations still resolve): CFC_TRANSFORMER_STAGE_SPECS (cf-pipeline.ts), COMMONFABRIC_RUNTIME_EXPORT_REGISTRY (+ its runner-factory guard test), CrossStageState, getExpressionContainerKind, SES_SELF_CONTAINED_CALLBACK_BOUNDARIES, wrapper vocabulary in schema-generator/src/typescript/wrapper-names.ts, CFC_CANONICAL_ALIAS_NAMES in packages/api/cfc.ts, and the JSONSchema type in packages/api/index.ts. Mechanical stage claims are pinned by packages/ts-transformers/test/spec-sync.test.ts.
• Cross-package contracts with no single home (historically the blind spot): transformer emission ↔ runner sandbox verifier (@commonfabric/utils sandbox contract); pattern-coverage ↔ runner line-offset/cache couplings (runner/harness/engine.ts); bare WeakMap boundary with schema-generator (cross-stage-state.ts header); CFC aliases/policy markers ↔ schema generator ↔ policy compilation ↔ runner fail-closed IFC validation.

Known drift patterns (seeds, not the boundary)

• Landing-gap: a feature ships, spec sections that deny it stay (grep the spec for "not implemented", "no …yet", "draft" and test each such claim).
• Enumeration drift: prose lists (diagnostic ids, registry entries, stages, fixture suites) vs their constants — including the inverse direction (ids in code the spec never mentions).
• Rename shadows: file/symbol references in older docs after renames; git touch dates lie (mechanical rename PRs refresh mtimes without verifying).
• PR-scoped artifacts aging in place; "Effective date"/status headers nobody updates.
• Author-layer contradictions: docs/common, tutorials, and skills teaching constructs the validators reject — verify against validation.test.ts and the target-language matrix, and check the critic skills especially (their errors get amplified by automation).

Audit values

• Name the authority direction for every disagreement before deciding which side changes.
• Treat source, tests, and emitted output as evidence; another document's claim is only a lead.
• Use independent passes to raise confidence, never as a substitute for cited evidence.
• Preserve point-in-time records under docs/history/; correct live docs or implementation according to the task and the authority split.
• Make load-bearing enumerable facts mechanically checkable when practical. Historical audit precedents live at docs/history/cfc-spec-audit.md and docs/history/cts-docs-audit-2026-07.md.