@xemahq/kernel-contracts 0.22.3 → 0.23.0

package/src/capability/lib/shell-command-descriptor.ts

@@ -5,7 +5,7 @@ import { CapabilityRefSchema, type CapabilityRef } from './capability-ref';
  * Stub for a JSON Schema reference. Modelled as `{ $ref: string }` so
  * downstream services (notably `xema-shell-api`) can plug in their richer
  * `JsonSchemaRef` shape without the kernel having to know about JSON Schema
- * machinery. Phase-1A intentional scope limit.
+ * machinery. An intentional scope limit.
  */
 export interface JsonSchemaRefStub {
   $ref: string;
@@ -16,7 +16,7 @@ export const JsonSchemaRefStubSchema = z.object({
 }) as z.ZodType<JsonSchemaRefStub>;
 
 /**
- * `ShellCommandDescriptor` — plan §31.5. Single source of truth for human
+ * `ShellCommandDescriptor` — single source of truth for human
  * help (`xema help <cmd>`), agent help (the `xema-shell:run@1` self-describe
  * surface), and the host UI's command palette.
  *
@@ -28,7 +28,7 @@ export const JsonSchemaRefStubSchema = z.object({
  * depend on `@xemahq/xema-object-contracts`, which would form a kernel cycle
  * if `xema-object-contracts` ever needed a `CapabilityRef`.
  *
- * `safeForAgents` is enforced by `xema-capability-router` per §31.7 — the
+ * `safeForAgents` is enforced by `xema-capability-router` — the
  * descriptor is the source of truth; the gateway never relaxes it.
  */
 export interface ShellCommandDescriptor {

package/src/connector/lib/adapter-kind.ts

@@ -9,7 +9,7 @@
  *
  * The set is *built-in-closed but biome-extensible*: biomes may
  * contribute additional kinds via the future `AdapterContribution`
- * registry (Phase 7). The closed enum below names only the kinds the
+ * registry. The closed enum below names only the kinds the
  * platform ships out-of-the-box. Anything outside this list MUST be
  * either a built-in plus a biome contribution, or routed through an
  * opaque `AdapterKindRef` string captured below.

package/src/connector/lib/capability-refs.ts

@@ -6,7 +6,7 @@
 // contracts`); they version like syscalls (`@1`, `@2`, ...) and the runtime
 // MUST refuse to dispatch a major version it has not registered.
 //
-// Source of truth: plan §17.2-B item 2. This file is the registry seed; the
+// This file is the registry seed; the
 // `connector-gateway-api` capability dispatcher MAY consume it directly for
 // `name`-side validation.
 // ═══════════════════════════════════════════════════════════════════════════

package/src/connector/lib/connector-descriptor.ts

@@ -9,9 +9,10 @@
  * provider so ONE app credential (per `ProviderDescriptor`) backs many
  * connectors.
  *
- * This descriptor is the connector-registry face of an `IntegrationProvider
- * Module`: the module carries the executable webhook/action/resource handlers;
- * this descriptor carries the *catalog + connect* metadata the framework needs
+ * This descriptor is the connector-registry face of an
+ * `IntegrationProviderModule`: the module carries the executable
+ * webhook/action/resource handlers; this descriptor carries the
+ * *catalog + connect* metadata the framework needs
  * to render the provider-grouped catalog, drive consent with the right scopes,
  * and resolve the right per-connection credential kind.
  * ─────────────────────────────────────────────────────────────────────────

package/src/connector/lib/credential-kind.ts

@@ -1,11 +1,10 @@
 /**
  * Closed enum of credential strategies the platform knows how to mint,
- * cache, refresh and revoke. Biomes contributing new providers (Phase
- * 7) MUST declare one of these — they never ship custom mint code.
+ * cache, refresh and revoke. Biomes contributing new providers MUST
+ * declare one of these — they never ship custom mint code.
  *
  * Adding a kind here is a one-line schema change plus a matching
- * strategy implementation under
- * `apps/integration-adapters-api/src/credentials/strategies/<kind>/`.
+ * strategy implementation for that kind.
  */
 export enum CredentialKind {
   /** GitHub App / GitLab App style installation token (per-installation, 1h). */

package/src/connector/lib/envelope-schema.ts

@@ -11,7 +11,7 @@ import { BuiltInAdapterKind, type AdapterKindRef } from './adapter-kind';
  * evaluating to `false` at dispatch.
  *
  * The map is keyed by `(adapterKind, entityKind)`. When a webhook
- * filter declares its target `entityKind` (Phase 7 manifest field),
+ * filter declares its target `entityKind` (a manifest field),
  * the cross-validator narrows path checking to that entry. Filters
  * that omit `entityKind` fall back to the `UNION_ENTITY_KIND` entry,
  * which collects every path across the adapter's entity kinds — over-
@@ -167,7 +167,7 @@ registerEnvelopeSchema(BuiltInAdapterKind.Documentation, {
 
 /**
  * Register the per-entityKind permitted `$envelope.*` paths for a
- * biome-contributed AdapterKind (Phase 7). Built-in kinds are pre-
+ * biome-contributed AdapterKind. Built-in kinds are pre-
  * registered above. Re-registering an existing kind REPLACES its
  * entry set — `integration-adapters-api`'s registry is the authority,
  * so biome upgrades surface here.

package/src/connector/lib/filter-expr-validate.ts

@@ -56,7 +56,7 @@ export interface FilterExprPathIssue {
  * Statically validate that every `$envelope.*` path the predicate
  * references is permitted by the canonical envelope schema for
  * `(adapterKind, entityKind)`. `$selector` paths are NOT validated
- * here — selectors are opaque-by-design (Phase 3 lock-in): their
+ * here — selectors are opaque-by-design: their
  * shape is governed by the biome's install JSON Schema, not by a
  * kernel-level path map.
  *

package/src/connector/lib/filter-expr.ts

@@ -184,6 +184,8 @@ function scalarEqual(a: unknown, b: unknown): boolean {
  */
 const REGEX_CACHE = new Map<string, RegExp>();
 const REGEX_MAX_LEN = 256;
+/** Cap on distinct compiled patterns retained, to bound memory in a long-lived process. */
+const REGEX_CACHE_MAX = 1_000;
 
 function compileRegex(pattern: string): RegExp {
   const cached = REGEX_CACHE.get(pattern);
@@ -198,6 +200,12 @@ function compileRegex(pattern: string): RegExp {
   }
   try {
     const re = new RegExp(pattern);
+    // Evict the oldest entry (Map preserves insertion order) once the cache is
+    // full, so an unbounded stream of distinct patterns cannot grow it forever.
+    if (REGEX_CACHE.size >= REGEX_CACHE_MAX) {
+      const oldest = REGEX_CACHE.keys().next().value;
+      if (oldest !== undefined) REGEX_CACHE.delete(oldest);
+    }
     REGEX_CACHE.set(pattern, re);
     return re;
   } catch (cause) {

package/src/contribution/lib/contribution-kind.ts

@@ -5,16 +5,15 @@ import { z } from 'zod';
  * (biome) may contribute to the Xema OS through the Contribution Protocol
  * (XSI plane 2). Extending it is a one-line PR to the kernel.
  *
- * The seed set is documented in the Xema OS plan-of-record §12.1. Each
- * additional value below the v1 seed (e.g. `ShellCommand`, `DoctorCheck`) is
- * pulled from a specific section of the same plan and is cited inline.
+ * The v1 seed set is grouped first below. Each additional value beyond the
+ * v1 seed (e.g. `ShellCommand`, `DoctorCheck`) extends the closed enum.
  *
  * Enum string values match the slug spoken by the rest of the protocol
  * (Capability References, manifest declarations) so that round-tripping
  * between the enum and the wire is lossless.
  */
 export enum ContributionKind {
-  // -- v1 seed (plan §12.1) -------------------------------------------------
+  // -- v1 seed ---------------------------------------------------------------
   ConnectorBinding = 'connector-binding',
   MountSource = 'mount-source',
   McpTool = 'mcp-tool',
@@ -29,13 +28,13 @@ export enum ContributionKind {
   ModelResolutionDimension = 'model-resolution-dimension',
   WidgetKind = 'widget-kind',
 
-  // -- Xema Shell additions (plan §31.5 / §31.9) ---------------------------
-  /** A command descriptor contributed to the Xema Shell. Plan §31.5. */
+  // -- Xema Shell additions --------------------------------------------------
+  /** A command descriptor contributed to the Xema Shell. */
   ShellCommand = 'shell-command',
-  /** A `xema doctor` health check contributed by a biome. Plan §31.9. */
+  /** A `xema doctor` health check contributed by a biome. */
   DoctorCheck = 'doctor-check',
 
-  // -- Registry gaps closed (plan §17.12) ----------------------------------
+  // -- Registry gaps closed --------------------------------------------------
   /**
    * An artifact type contributed by a biome to the artifact-store schema-
    * version registry (`ArtifactTypeRegistryService`). The registry adapter
@@ -49,8 +48,8 @@ export enum ContributionKind {
    */
   InquiryKind = 'inquiry-kind',
 
-  // -- Phase C absorption (plan §6 C.2) ------------------------------------
-  // The Phase-C "Contribution Protocol" rollup is the single source of
+  // -- Contribution-absorption additions -------------------------------------
+  // The "Contribution Protocol" rollup is the single source of
   // truth for every kind of contribution a biome can ship. A biome's
   // `contributions/` directory replaces the legacy `content/` + `modules/`
   // seeders. Per-kind handlers are wired through
@@ -105,7 +104,7 @@ export enum ContributionKind {
   /** A runtime-mount kind module contributed by a biome. */
   RuntimeMountKind = 'runtime-mount-kind',
 
-  // -- Phase H#2: capability self-registration (plan §6.H) -----------------
+  // -- Capability self-registration ------------------------------------------
   /**
    * A `CapabilityRef` descriptor contributed by a biome — title, summary,
    * I/O schemas, risk tier, and approval flag. The boot-time codemod
@@ -122,7 +121,7 @@ export enum ContributionKind {
    */
   Capability = 'capability',
 
-  // -- Phase 5: resource-ownership self-registration -----------------------
+  // -- Resource-ownership self-registration ----------------------------------
   /**
    * A resource-instance ownership/visibility declaration contributed by a
    * biome — `resourceType` + `resourceId` + a `ResourceVisibilityPattern` +

package/src/contribution/lib/contribution-source.ts

@@ -2,8 +2,7 @@ import { z } from 'zod';
 
 /**
  * `ContributionSource` is the 5-tier scope at which a Contribution lives.
- * Value-identical to `SkillSpace` and `AgentSpace` (see
- * `.claude/rules/skills-and-composition.md`) — the three enums share ONE
+ * Value-identical to `SkillSpace` and `AgentSpace` — the three enums share ONE
  * ownership / scope model and must not drift.
  *
  * Precedence — **most specific wins**:

package/src/contribution/lib/contribution.ts

@@ -109,8 +109,6 @@ export const ContributionVersionSchema = z
  * regardless of `kind`, carries this shape. Kind-specific contracts packages
  * own their own `TManifest` Zod schemas and feed them to
  * `contributionEnvelopeSchema` to get a fully-typed runtime validator.
- *
- * See plan-of-record §12.2 for the prose definition.
  */
 export interface Contribution<
   TKind extends ContributionKind,
@@ -175,11 +173,10 @@ export interface ContributionIngestContext {
 }
 
 /**
- * Per-kind ingestion handler. Phase C of the Xema OS plan replaces 14 hand-
+ * Per-kind ingestion handler. The Contribution Protocol replaces 14 hand-
  * rolled `Bootstrap*Service` seeders with a single generic
- * `BootstrapContributionsService<TKind, TManifest>` template (see plan §6
- * C.3) whose only per-kind specialisation is an implementation of this
- * interface.
+ * `BootstrapContributionsService<TKind, TManifest>` template whose only
+ * per-kind specialisation is an implementation of this interface.
  *
  * Implementations MUST:
  * - pin `kind` to the concrete `ContributionKind` they handle so the

package/src/document-render/lib/render-enums.ts

@@ -1,7 +1,6 @@
 /**
  * Closed enums for the render service wire. Real TS enums (not
- * string-literal unions) so OpenAPI/Orval emit stable enum schemas — see
- * `docs/API_STANDARDS.md` and `.claude/rules/backend.md`.
+ * string-literal unions) so OpenAPI/Orval emit stable enum schemas.
  */
 
 /**

package/src/execution-context/lib/caller.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 /**
- * Closed caller-kind set (plan v4.3 §A.3).
+ * Closed caller-kind set.
  *
  * Distinguishes how the invocation entered the system — drives audit
  * shape, default obligations (e.g. `Web` callers default to `audit` +
@@ -21,7 +21,7 @@ export const CallerKindSchema = z.nativeEnum(CallerKind);
 /**
  * `Caller` — entry-point envelope captured on every invocation.
  *
- * v4.3 contract shape per plan §A.3:
+ * Contract shape:
  *   { kind: CallerKind; appId?; sessionId?; ip?; userAgent? }
  *
  * `appId` and `sessionId` are populated when the caller is an embedded

package/src/execution-context/lib/execution-context.ts

@@ -30,8 +30,7 @@ import {
 } from './subject';
 
 /**
- * Closed biome trust-tier set referenced by `ExecutionContext.biome`
- * (plan v4.3 §A.3).
+ * Closed biome trust-tier set referenced by `ExecutionContext.biome`.
  *
  * Tier ordering goes Untrusted → Community → Verified → Official; OPA
  * policy bundles MAY gate a capability to a minimum tier, but the kernel
@@ -48,8 +47,8 @@ export enum BiomeTrustTier {
 export const BiomeTrustTierSchema = z.nativeEnum(BiomeTrustTier);
 
 /**
- * Biome attestation block carried on `ExecutionContext.biome` (plan
- * v4.3 §A.3). Set when the capability is provided by a biome (vs. an
+ * Biome attestation block carried on `ExecutionContext.biome`.
+ * Set when the capability is provided by a biome (vs. an
  * embedded built-in). `signatureVerified` is the Cosign verdict from the
  * biome-fetcher-api at install time.
  */
@@ -68,8 +67,7 @@ export const ExecutionContextBiomeSchema = z.object({
 }) as z.ZodType<ExecutionContextBiome>;
 
 /**
- * Environment block carried on `ExecutionContext.environment` (plan
- * v4.3 §A.3).
+ * Environment block carried on `ExecutionContext.environment`.
  *
  * `id` is the canonical `environment:<slug>` ref (string-typed here to
  * keep the envelope JSON-clean — the kernel-side reference type lives in the
@@ -89,8 +87,7 @@ export const ExecutionContextEnvironmentSchema = z.object({
 }) as z.ZodType<ExecutionContextEnvironment>;
 
 /**
- * Capability block carried on `ExecutionContext.capability` (plan
- * v4.3 §A.3).
+ * Capability block carried on `ExecutionContext.capability`.
  *
  * `ref` is the canonical capability reference (`<biome>:<verb>@<major>`).
  * `inputHash` is an optional SHA-256 fingerprint of the JSON-serialised
@@ -108,7 +105,7 @@ export const ExecutionContextCapabilitySchema = z.object({
 }) as z.ZodType<ExecutionContextCapability>;
 
 /**
- * Resource block carried on `ExecutionContext.resource` (plan v4.3 §A.3).
+ * Resource block carried on `ExecutionContext.resource`.
  *
  * Set when the invocation targets a specific persistent object (a
  * XemaObject, a document, an SCM file). `ref` is the resource reference
@@ -127,8 +124,7 @@ export const ExecutionContextResourceSchema = z.object({
 }) as z.ZodType<ExecutionContextResource>;
 
 /**
- * Constraints block carried on `ExecutionContext.constraints` (plan
- * v4.3 §A.3).
+ * Constraints block carried on `ExecutionContext.constraints`.
  *
  * Per-invocation caps + flags the gateway derives from the caller's
  * grant, the org's environment policy, and the capability's defaults.
@@ -155,14 +151,14 @@ export const ExecutionContextConstraintsSchema = z.object({
 }) as z.ZodType<ExecutionContextConstraints>;
 
 /**
- * `ExecutionContext` — the per-invocation envelope (plan v4.3 §A.3).
+ * `ExecutionContext` — the per-invocation envelope.
  *
- * Constructed by `biomes/xema-capability-router/api/xema-capability-router` at the gateway boundary,
+ * Constructed by the capability router at the gateway boundary,
  * passed verbatim to `authorization-api` for the policy check, and
  * forwarded to the dispatched runner. Audit, policy, and runner all
  * read the SAME shape — no parallel envelopes.
  *
- * Wave 4 (Phase A.5) wires this through `dispatch.service.ts`. This
+ * The dispatch pipeline wires this through at runtime. This
  * package is contract-only — no consumer rewiring lives here.
  */
 export interface ExecutionContext {
@@ -180,15 +176,13 @@ export interface ExecutionContext {
   /**
    * RFC 8693 delegation chain (`act`), outermost-acting-first. Built at the
    * gateway from `RequestContext.actorChain` and carried through policy → audit
-   * → credential-broker. Empty/omitted for a non-delegated invocation
-   * (plan §W4 / Pillar 3.2).
+   * → credential-broker. Empty/omitted for a non-delegated invocation.
    */
   actorChain?: ActingForRef[];
   /**
    * Opaque credential-binding id the PDP selected for this invocation
    * (`PolicyDecision.credentialBindingId`). When present, the executing
-   * gateway/runner resolves it via the credential-broker. NEVER a secret
-   * (plan §W4 / Pillar 3.2).
+   * gateway/runner resolves it via the credential-broker. NEVER a secret.
    */
   credentialBindingId?: string;
   /**

package/src/execution-environment/lib/approval-rule.ts

@@ -5,8 +5,8 @@ import {
 } from '../../capability';
 
 /**
- * Per-environment approval rule (plan §3.4 `ExecutionEnvironment.approvalRules[]`,
- * §30.7 Human-in-the-loop approval at runtime).
+ * Per-environment approval rule (`ExecutionEnvironment.approvalRules[]`):
+ * human-in-the-loop approval at runtime.
  *
  * When a runtime invocation matches a rule whose `capability` ref covers the
  * call, the gateway suspends the invocation, emits an `ApprovalRequested`

package/src/execution-environment/lib/built-in-environments.ts

@@ -3,13 +3,12 @@ import { z } from 'zod';
 /**
  * Closed set of built-in Execution Environment kinds.
  *
- * Plan-of-record: v4.3 §2 vocabulary table (`Zone → Environment` row),
- * §3.4 (the eight built-in environments that cover every story we have
- * today), and §30.6 (`trusted-dev` environment — the developer escape
- * hatch).
+ * There are eight built-in environments that cover every story we have
+ * today, plus the `trusted-dev` environment — the developer escape
+ * hatch.
  *
  * v1 ships ONLY these built-ins; custom environments are an explicit v2
- * extension (plan §16). The downstream `ExecutionEnvironment.scope` type
+ * extension. The downstream `ExecutionEnvironment.scope` type
  * intentionally widens to `ExecutionEnvironmentKind | string` for future-
  * proofing, but at v1 the only legal scope values are members of this
  * enum — see `isExecutionEnvironmentKind`.
@@ -40,7 +39,7 @@ export enum ExecutionEnvironmentKind {
   /** Biome inspected for publication; no real org data access. */
   StoreReview = 'store-review',
   /**
-   * Local-dev / personal-sandbox environment (plan §30.6). Inside it the
+   * Local-dev / personal-sandbox environment. Inside it the
    * Capability Gateway grants every capability the biome *declared* in
    * its manifest, no resource glob, no rate limit, no human approval.
    * Audit-log still records every call so devs can inspect what their
@@ -55,12 +54,11 @@ export const ExecutionEnvironmentKindSchema = z.nativeEnum(ExecutionEnvironmentK
 
 /**
  * Stable, ordered list of every built-in environment slug. Seeded at
- * boot by `authorization-api` / `object-registry-api` per plan §17.5
- * step 1.
+ * boot by `authorization-api` / `object-registry-api`.
  *
  * Ordering is intentional (system → org → project → app → session →
- * sandbox → public → store-review → trusted-dev) and matches the table
- * in §3.4 followed by the dev escape hatch from §30.6. Do not reorder
+ * sandbox → public → store-review → trusted-dev) — the built-in
+ * environments followed by the dev escape hatch. Do not reorder
  * without a coordinated migration of any consumer that relies on
  * positional iteration.
  */
@@ -79,7 +77,7 @@ export const BUILT_IN_ENVIRONMENT_SLUGS: readonly ExecutionEnvironmentKind[] = [
 /**
  * Narrowing guard: returns `true` iff `slug` is one of the built-in
  * environment slugs. Used by `ExecutionEnvironmentSchema` and the
- * authorization-api to refuse custom-scoped environments at v1 (plan §16
+ * authorization-api to refuse custom-scoped environments at v1 (a
  * non-goal).
  */
 export function isExecutionEnvironmentKind(

package/src/execution-environment/lib/execution-environment.ts

@@ -13,7 +13,7 @@ import {
 import { ApprovalRuleSchema, type ApprovalRule } from './approval-rule';
 
 /**
- * Canonical Execution Environment Reference grammar (plan §3.4):
+ * Canonical Execution Environment Reference grammar:
  *
  *   `environment:<slug>`
  *
@@ -22,7 +22,7 @@ import { ApprovalRuleSchema, type ApprovalRule } from './approval-rule';
  * silently absorb a free-form string.
  *
  * v1 only mints refs whose slug is an `ExecutionEnvironmentKind` value
- * (plan §16 forbids custom environments). The type still validates the
+ * (custom environments are forbidden at v1). The type still validates the
  * *grammar* — semantic "built-in-only" enforcement lives one layer up
  * in `authorization-api`, which calls
  * `isExecutionEnvironmentKind(parseEnvironmentRef(ref).slug)`.
@@ -127,8 +127,8 @@ export const BUILT_IN_ENVIRONMENT_REFS: Record<
 );
 
 /**
- * Runtime budget caps the environment advertises to the gateway (plan §3.4
- * `ExecutionEnvironment.runtimeLimits`). All fields are optional — omitted means
+ * Runtime budget caps the environment advertises to the gateway
+ * (`ExecutionEnvironment.runtimeLimits`). All fields are optional — omitted means
  * "no cap from the environment", but the gateway may still apply org- or
  * grant-level caps. None of these fields fall back to a hidden default.
  */
@@ -147,13 +147,13 @@ export const RuntimeLimitsSchema = z.object({
 }) as z.ZodType<RuntimeLimits>;
 
 /**
- * Allow-list of knowledge scope refs reachable from this environment (plan §3.4
- * `ExecutionEnvironment.allowedKnowledgeScopes`).
+ * Allow-list of knowledge scope refs reachable from this environment
+ * (`ExecutionEnvironment.allowedKnowledgeScopes`).
  *
  * v1 keeps the shape minimal — the ref string is sufficient for the
- * sandbox→prod boundary check that lands in Phase 4. Detailed per-scope
- * sub-schemas (e.g. spaces, page subtrees, redaction rules) are scheduled
- * for the knowledge-base-api Phase 4+ companion plan.
+ * planned sandbox→prod boundary check. Detailed per-scope
+ * sub-schemas (e.g. spaces, page subtrees, redaction rules) are deferred
+ * to a later phase.
  */
 export interface KnowledgePolicy {
   allowedRefs: readonly string[];
@@ -164,13 +164,13 @@ export const KnowledgePolicySchema = z.object({
 }) as z.ZodType<KnowledgePolicy>;
 
 /**
- * Allow-list of connector binding refs reachable from this environment (plan §3.4
- * `ExecutionEnvironment.allowedConnectors`).
+ * Allow-list of connector binding refs reachable from this environment
+ * (`ExecutionEnvironment.allowedConnectors`).
  *
  * v1 keeps the shape minimal — the ref string is sufficient for the
- * sandbox→prod boundary check that lands in Phase 4. Per-connector
+ * planned sandbox→prod boundary check. Per-connector
  * permission detail (per-repo globs, per-tracker projects, etc.) is
- * scheduled for the connector-gateway-api companion plan.
+ * deferred to a later phase.
  */
 export interface ConnectorPolicy {
   allowedRefs: readonly string[];
@@ -181,13 +181,13 @@ export const ConnectorPolicySchema = z.object({
 }) as z.ZodType<ConnectorPolicy>;
 
 /**
- * Allow-list of biome refs that may run inside this environment (plan §3.4
- * `ExecutionEnvironment.allowedBiomes`).
+ * Allow-list of biome refs that may run inside this environment
+ * (`ExecutionEnvironment.allowedBiomes`).
  *
  * v1 keeps the shape minimal — the ref string is sufficient for the
- * built-in-environment install policy that lands in Phase 4 / Phase 6. Lifecycle-
- * stage restrictions (draft / published / archived) are scheduled for the
- * biome-host-api companion plan.
+ * planned built-in-environment install policy. Lifecycle-
+ * stage restrictions (draft / published / archived) are deferred to a
+ * later phase.
  */
 export interface BiomePolicy {
   allowedRefs: readonly string[];
@@ -198,13 +198,12 @@ export const BiomePolicySchema = z.object({
 }) as z.ZodType<BiomePolicy>;
 
 /**
- * Allow-list of mount-source refs reachable from this environment (plan §3.4
- * `ExecutionEnvironment.allowedMounts`).
+ * Allow-list of mount-source refs reachable from this environment
+ * (`ExecutionEnvironment.allowedMounts`).
  *
  * v1 keeps the shape minimal — the ref string is sufficient for the
- * XVFS read/write boundary check that lands in Phase 4 / Phase 5. Per-mount
- * read/write splitting and path globs are scheduled for the xema-shell-api
- * companion plan.
+ * planned XVFS read/write boundary check. Per-mount
+ * read/write splitting and path globs are deferred to a later phase.
  */
 export interface MountPolicy {
   allowedRefs: readonly string[];
@@ -215,7 +214,7 @@ export const MountPolicySchema = z.object({
 }) as z.ZodType<MountPolicy>;
 
 /**
- * `ExecutionEnvironment` — the canonical permission-plane object (plan §3.4).
+ * `ExecutionEnvironment` — the canonical permission-plane object.
  *
  * An environment declares the capability surface, knowledge/connector/biome/mount
  * allow-lists, approval rules, and runtime budget that apply to every
@@ -232,7 +231,7 @@ export interface ExecutionEnvironment {
   /**
    * The environment's logical scope. v1 only accepts
    * `ExecutionEnvironmentKind` slugs; the string-side of the union is
-   * reserved for v2 custom environments (plan §16 non-goal at v1).
+   * reserved for v2 custom environments (a non-goal at v1).
    */
   scope: ExecutionEnvironmentKind | string;
   allowedCapabilities: CapabilityPolicy[];
@@ -250,7 +249,7 @@ export const ExecutionEnvironmentSchema = z.object({
     (s) => isExecutionEnvironmentKind(s),
     {
       message:
-        'ExecutionEnvironment.scope must be an ExecutionEnvironmentKind slug at v1; custom environments are a v2 extension (plan §16).',
+        'ExecutionEnvironment.scope must be an ExecutionEnvironmentKind slug at v1; custom environments are a v2 extension.',
     },
   ),
   allowedCapabilities: z.array(CapabilityPolicySchema),

package/src/inquiry/index.ts

@@ -6,8 +6,7 @@
 // kind-specific schema, aggregate per a policy, return a verdict."
 //
 // Runtime-agnostic. Pure types + Zod schemas. Zero framework / persistence /
-// workflow-runtime imports. The plan-of-record lives at
-// .claude/plans/i-think-what-we-ve-transient-zebra.md.
+// workflow-runtime imports.
 //
 // Per-kind prompt + reply Zod schemas live in their own contract packages
 // (`@xemahq/decision-gate-contracts`, `@xemahq/agent-tool-inquiry-

package/src/invocation/lib/invocation-mode.ts

@@ -7,7 +7,7 @@ import { z } from 'zod';
  * hint a mode via `ExecutionRequirements.mode`, but policy may override it.
  *
  * - `Sync` — the caller holds the request open until the composition produces
- *   its root structured output. The smallest correct slice (Phase 1).
+ *   its root structured output. The smallest correct slice.
  * - `Async` — the runtime returns immediately with a `Queued`/`Running`
  *   invocation; the caller polls the Invocation record for the terminal state.
  * - `Event` — the runtime returns without an `output`; the result is delivered

package/src/invocation/lib/invocation-record.ts

@@ -11,7 +11,7 @@ import {
  * per invocation. This is the source of truth for an invocation's lifecycle
  * (never the underlying session).
  *
- * `inputRef`/`outputRef` are blob/JSON references (inline JSON in Phase 1,
+ * `inputRef`/`outputRef` are blob/JSON references (inline JSON initially,
  * artifact-store refs once payloads grow). Timestamps are ISO-8601 strings.
  */
 export interface InvocationRecord {

package/src/invocation/lib/isolation-level.ts

@@ -7,7 +7,7 @@ import { z } from 'zod';
  *   default for mail (org+mailbox+emailThreadId): thread context is NEVER
  *   reused across unrelated emails.
  * - `PooledThread` — reuse a warm thread within the same `threadKey` (a warm
- *   session-pool optimization; future, Phase 3).
+ *   session-pool optimization; a future step).
  *
  * Closed set on purpose — both levels are honored by the runtime's pool/thread
  * management; adding a level is a coordinated kernel change.

package/src/kernel-state/lib/adapter-kind.ts

@@ -1,10 +1,10 @@
 /**
- * KernelState adapter kinds (plan §6 Phase D.3 — locked decision L9).
+ * KernelState adapter kinds.
  *
- * The plan explicitly closes the set to TWO adapters. There is no
+ * The set is explicitly closed to TWO adapters. There is no
  * Postgres adapter for KernelState; Postgres is reserved for service
  * domain data. Two DB engines max in any deployment is a load-bearing
- * invariant — do NOT extend this enum without updating L9.
+ * invariant — do NOT extend this enum.
  *
  * - `Sqlite` — file at `~/.xema/dev/kernel-state.sqlite` (dev) or
  *   `/var/lib/xema/kernel-state.sqlite` (single-instance). Advisory

package/src/kernel-state/lib/kernel-state.ts

@@ -1,5 +1,5 @@
 /**
- * KernelState client contract (plan §6 Phase D.3).
+ * KernelState client contract.
  *
  * KernelState is the kernel's single strongly-consistent KV / lease /
  * watch primitive. Every adapter (SQLite or etcd — see

package/src/kernel-state/lib/key-grammar.ts

@@ -1,5 +1,5 @@
 /**
- * KernelState key grammar (plan §6 Phase D.4).
+ * KernelState key grammar.
  *
  * Every key written to KernelState MUST start with one of the prefixes
  * below. The boundary CI script `check-kernel-state-key-ownership.mjs`

package/src/mcp-tool/lib/tool-selection.ts

@@ -11,7 +11,7 @@ import { ToolProviderKind, toolProviderKindSchema } from './provider-kind';
  * or BiomeInstallation.id) depending on `providerKind`. Cross-org
  * misuse is blocked at every layer (selection PATCH validation,
  * resolver scope binding, bridge token scope, data-layer WHERE
- * clauses) — see `.claude/plans/we-have-integrations-as-swift-haven.md`.
+ * clauses).
  *
  * `toolName` is the canonical MCP tool name as exposed by the
  * provider's `listTools` (NOT a slug; the value MCP clients invoke).

package/src/object/lib/object-lifecycle.ts

@@ -4,8 +4,7 @@ import { z } from 'zod';
  * Lifecycle every versioned XemaObject moves through. Mirrors
  * `AgentLifecycle` from `@xemahq/agent-composition-contracts` —
  * the two enums MUST stay value-identical (one ownership model across
- * the four primitives + every other XemaObject kind, per
- * `.claude/rules/skills-and-composition.md`).
+ * the four primitives + every other XemaObject kind).
  *
  * - `Draft` — internal revision; never resolved, never installable,
  *   never referenced by a lockfile.