ContextOS Spec Steward
Make the smallest coherent change to the public spec and its typed reference. New patterns belong in the spec only after validation in a working system; label proposals instead of presenting unproven concepts as canonical.
Establish current truth
- Locate the repository root and read the closest
AGENTS.md plus repository architecture guidance.
- Read the primary spec page, adjacent foundation/implementation pages, current TypeScript types/compiler/scenario, published schemas, and relevant tests.
- Search before claiming a primitive or control is absent. Include the foundations docs, implementation docs, typed reference, schemas, and—when the claim is about publication—the actual rendered/live surface if available.
- If instructions, docs, code, or schemas disagree, stop and state the conflict. Do not silently blend conventions.
Read references/change-map.md for semantic touch sets and validation routing.
Classify the change
Determine whether the request is:
- explanatory wording with no contract change;
- canonical terminology or taxonomy change;
- type/schema/envelope evolution;
- compiler behavior change;
- canonical scenario/example change;
- new operational pattern or proposed extension.
Write down the invariant being changed and the compatibility expectation before editing. For schema-level work, apply the same compatibility-first sequence across types, producers, schemas, examples, docs, and tests.
Preserve ContextOS invariants
- The docs are the spec;
src/lib/contextos/ is the small deterministic typed reference, not a production runtime.
- Routing, policy, retry, budget, admission, risk, and threshold decisions are deterministic and fail closed. No random or clock-dependent branching.
- The five planes retain clear ownership; cross-cutting types are seams, not excuses to collapse boundaries.
- Native
ActionRisk dimensions remain independent. ApprovalMode is only a compatibility projection.
- Retrieved evidence and memory are data-only; untrusted content never grants authority.
- Required evidence conflicts remain visible and block commit until resolved by an accountable rule or reviewer.
- External effects flow through typed tool envelopes, scoped identity, policy, approval where required, postcondition checks, and recoverability semantics.
- Tests enforce intent. Do not weaken them or widen allowlists to make new content pass.
Edit surgically
Use the coupling map as a maximum coherent set, not a checklist of files to touch. Update only surfaces whose observable contract changes. Keep canonical IDs and examples sourced from the scenario fixture rather than copying stale variants.
When adding a concept, define:
- plane owner and boundary;
- inputs/outputs and typed seam;
- enforcement point;
- failure mode and fail-closed behavior;
- evidence, audit, and replay implications;
- compatibility/migration posture;
- evaluation and operational ownership.
Call out non-canonical extensions explicitly. Do not add a type solely because prose benefits from a convenient noun.
Verify
Run the narrowest relevant tests first, then typecheck/lint/full tests/build in proportion to the surface. Inspect the diff for accidental terminology changes and verify published routes/assets when touched.
Report changed invariants, coupled surfaces actually updated, compatibility decision, checks run, and anything unverified.
1---2name: contextos-spec-steward3description: Change the ContextOS canonical specification and typed reference implementation without semantic drift, conflicting conventions, or unnecessary scope. Use for runtime-model, terminology, compiler, or cross-plane spec changes in the ContextOS repository; not for ordinary site styling.4---56# ContextOS Spec Steward78Make the smallest coherent change to the public spec and its typed reference. New patterns belong in the spec only after validation in a working system; label proposals instead of presenting unproven concepts as canonical.910## Establish current truth11121. Locate the repository root and read the closest `AGENTS.md` plus repository architecture guidance.132. Read the primary spec page, adjacent foundation/implementation pages, current TypeScript types/compiler/scenario, published schemas, and relevant tests.143. Search before claiming a primitive or control is absent. Include the foundations docs, implementation docs, typed reference, schemas, and—when the claim is about publication—the actual rendered/live surface if available.154. If instructions, docs, code, or schemas disagree, stop and state the conflict. Do not silently blend conventions.1617Read [references/change-map.md](references/change-map.md) for semantic touch sets and validation routing.1819## Classify the change2021Determine whether the request is:2223- explanatory wording with no contract change;24- canonical terminology or taxonomy change;25- type/schema/envelope evolution;26- compiler behavior change;27- canonical scenario/example change;28- new operational pattern or proposed extension.2930Write down the invariant being changed and the compatibility expectation before editing. For schema-level work, apply the same compatibility-first sequence across types, producers, schemas, examples, docs, and tests.3132## Preserve ContextOS invariants3334- The docs are the spec; `src/lib/contextos/` is the small deterministic typed reference, not a production runtime.35- Routing, policy, retry, budget, admission, risk, and threshold decisions are deterministic and fail closed. No random or clock-dependent branching.36- The five planes retain clear ownership; cross-cutting types are seams, not excuses to collapse boundaries.37- Native `ActionRisk` dimensions remain independent. `ApprovalMode` is only a compatibility projection.38- Retrieved evidence and memory are data-only; untrusted content never grants authority.39- Required evidence conflicts remain visible and block commit until resolved by an accountable rule or reviewer.40- External effects flow through typed tool envelopes, scoped identity, policy, approval where required, postcondition checks, and recoverability semantics.41- Tests enforce intent. Do not weaken them or widen allowlists to make new content pass.4243## Edit surgically4445Use the coupling map as a maximum coherent set, not a checklist of files to touch. Update only surfaces whose observable contract changes. Keep canonical IDs and examples sourced from the scenario fixture rather than copying stale variants.4647When adding a concept, define:4849- plane owner and boundary;50- inputs/outputs and typed seam;51- enforcement point;52- failure mode and fail-closed behavior;53- evidence, audit, and replay implications;54- compatibility/migration posture;55- evaluation and operational ownership.5657Call out non-canonical extensions explicitly. Do not add a type solely because prose benefits from a convenient noun.5859## Verify6061Run the narrowest relevant tests first, then typecheck/lint/full tests/build in proportion to the surface. Inspect the diff for accidental terminology changes and verify published routes/assets when touched.6263Report changed invariants, coupled surfaces actually updated, compatibility decision, checks run, and anything unverified.
contextosai