Curated Documentation Surface

CX Documentation

Kernel-owned proof path, live MCP workspace surface, and durable cognition notes.

Status: reviewed. Recommendation: Option C.

No implementation is implied by this page until Werner approves the recommendation.

Problem Statement

Today cx bundle aborts on unsafe_dirty with exit code 7. That conflates two questions: is the workspace clean, and is this artifact acceptable for a handoff gate?

Phase 3 separates workflow cleanliness from artifact verification.

Proposal

cx bundle can always produce a bundle. The manifest gains a purity field:

Purity Meaning

pristine

clean tree, all tracked files committed, no overrides

safe_dirty

untracked files only

forced_dirty

tracked changes, operator override

ci_dirty

tracked changes, CI override

Reviewers, CI, and cx verify gate on purity; the bundle command does not under Option B. Option C keeps the current bundle-time abort as the default and lets operators explicitly choose warning or off modes.

Marcus’s Objection

If cx bundle always succeeds, the purity field can become ignored noise. Operators may stop noticing that a handoff artifact was produced from tracked drift.

Counter-proposal: keep abort behavior by default, but allow CX_PURITY_GATE=warn for power users who intentionally want materialization without aborting.

Kira’s Objection

CI pipelines currently rely on exit code 7. A migration must include cx verify --require-purity=pristine, a deprecation timeline, and no compatibility shim unless Werner explicitly approves it.

Trust Spectrum Impact

Moving the check to verification weakens the statement that the CLI refuses to materialize ambiguous artifacts. It strengthens the verifier contract only if every downstream workflow uses the verifier as the authoritative gate.

The philosophical tradeoff is whether materialization itself is a trust boundary or merely an input to the next trust boundary.

Notes Impact

Phase 3 must update notes before code lands. The leading note changes are:

  • notes/Dirty State Taxonomy.md must distinguish dirty-state provenance from the proposed manifest purity field.

  • notes/Audited Override Pattern.md must explain how bundle.purity_gate changes operator intent without hiding tracked drift.

  • notes/System Trust Contract.md must be reviewed because Option B or C changes the claim that the CLI refuses to materialize ambiguous artifacts.

The PR template for any Phase 3 implementation should require a note diff in the same PR as code. If no note changes are needed, the PR must say why.

Decision

Option A: status quo. Keep abort behavior. Recommend this if discoverability and naive-operator safety dominate.

Option B: full move to materialization-time. Bundle always succeeds and verifier gates purity.

Option C: hybrid. Add bundle.purity_gate = "abort" | "warn" | "off" with default abort.

Recommendation: Option C.

Rationale:

  • It preserves the current trust contract for new and casual operators.

  • It gives expert workflows an explicit configuration key instead of overloading --force.

  • It lets CI migrate deliberately to cx verify --require-purity=pristine without losing exit-code protection during the transition.

  • It keeps purity visible in both places that matter: materialization warnings and verifier gates.

Rejected for now:

  • Option A leaves power users with only ad hoc local overrides.

  • Option B weakens the materialization trust boundary too abruptly and risks making purity easy to ignore.

Implementation Sketch

If Option C is approved, update:

  • manifest schema/types with purity while preserving the existing dirty-state taxonomy only as the recorded provenance source;

  • config loading for bundle.purity_gate = "abort" | "warn" | "off", default abort;

  • bundle dirty-state enforcement so abort keeps exit code 7, warn materializes with a warning, and off materializes quietly while still recording manifest purity;

  • verify with --require-purity=pristine;

  • CLI docs and audited-overrides docs;

  • tests for default abort, warn/off materialization, manifest purity, and CI verifier gating.