@xemahq/kernel-contracts 0.22.3 → 0.23.1

package/src/biome/lib/biome-manifest.ts

@@ -56,8 +56,8 @@ import {
 export const BIOME_MANIFEST_FILENAME = 'xema-biome.json';
 
 /**
- * Declarative event subscription entry of the biome manifest
- * (plan §12.4). `event` is the CloudEvents `type` the biome subscribes
+ * Declarative event subscription entry of the biome manifest.
+ * `event` is the CloudEvents `type` the biome subscribes
  * to (e.g. `xema.kb.page.published.v1`); `handlerModule` is the module
  * path relative to the biome package root that `biome-host-api` loads
  * to dispatch matching events.
@@ -94,19 +94,18 @@ const ManifestBiomeScopeSchema = z.enum([
 ]);
 
 /**
- * The Contribution Protocol (`@xemahq/kernel-contracts/contribution`) is the
- * single authoritative enum for kinds a biome may ship.
+ * Canonical map from a content-kind token to its conventional on-disk
+ * directory name. Biome content is discovered by walking these directories
+ * for on-disk presence (the file-walk seeders); the kind tokens themselves
+ * correspond to the Contribution Protocol
+ * (`@xemahq/kernel-contracts/contribution`). Multi-file bundle kinds (agents,
+ * skills, workflows, …) live under these dirs; single-file/typed
+ * contributions may alternatively use the `xema.contributions` block.
  *
- * Conventional on-disk directory name per `ships.content[]` / `ships.modules[]`
- * string. Used ONLY for the `ships`-based file-walk seeders that have not yet
- * migrated to the `contributions/` directory protocol. New code MUST use the
- * `xema.contributions` block (or inline contributions) instead of
- * `ships.content` / `ships.modules`.
- *
- * Keys are the camelCase tokens accepted in `xema-biome.json`; the mapping
- * returns `null` for any key it does not recognise so callers can fail fast.
+ * Keys are the camelCase tokens; the mapping throws for any key it does not
+ * recognise so callers fail fast.
  */
-const LEGACY_SHIPS_CONTENT_DIR: Readonly<Record<string, string>> = {
+const CONTENT_KIND_DIR: Readonly<Record<string, string>> = {
   agents: 'agents',
   workflowConfig: 'workflow-config',
   deliverableSpecs: 'deliverable-specs',
@@ -127,16 +126,16 @@ const LEGACY_SHIPS_CONTENT_DIR: Readonly<Record<string, string>> = {
 };
 
 /**
- * Resolve a legacy `ships.content[]` value to its conventional directory
- * name, or `null` for unknown tokens. Used by the legacy file-walk
- * catalog/seeders; new code should use the contributions protocol.
+ * Resolve a content-kind token to its conventional directory name. Used by
+ * the file-walk catalog/seeders that discover content by on-disk presence.
+ * Throws for an unknown token so callers fail fast.
  */
 export function contentKindToDir(kind: string): string {
-  const dir = LEGACY_SHIPS_CONTENT_DIR[kind];
+  const dir = CONTENT_KIND_DIR[kind];
   if (!dir) {
     throw new Error(
-      `biome-host-sdk: unknown legacy ships.content[] value "${kind}". ` +
-        `Either migrate the biome to xema.contributions or extend LEGACY_SHIPS_CONTENT_DIR.`,
+      `biome-host-sdk: unknown content kind "${kind}". ` +
+        `Either use the xema.contributions block or extend CONTENT_KIND_DIR.`,
     );
   }
   return dir;
@@ -155,7 +154,7 @@ export const BiomeDatabaseDeclarationSchema = z
 export type BiomeDatabaseDeclaration = z.infer<typeof BiomeDatabaseDeclarationSchema>;
 
 /**
- * Per-API declaration shipped under `xema.ships.apis[]` (Phase 9).
+ * Per-API declaration shipped under `xema.ships.apis[]`.
  * Each entry becomes one subdomain (`<name>.api.<base-domain>`)
  * served by a biome-shipped API service. biome-host-api applies
  * the Helm sub-chart at install time and writes a route-registry
@@ -227,7 +226,7 @@ export const BiomeApiDeclarationSchema = z
 export type BiomeApiDeclaration = z.infer<typeof BiomeApiDeclarationSchema>;
 
 /**
- * Phase-C Contribution Protocol entry. The body of an
+ * Contribution Protocol entry. The body of an
  * `*.contribution.json` file under a biome's `contributions/` directory,
  * or an inline entry under `xema.contributions.inline[]` in
  * `xema-biome.json`.
@@ -235,10 +234,7 @@ export type BiomeApiDeclaration = z.infer<typeof BiomeApiDeclarationSchema>;
  * Validated structurally here (kind + slug + opaque manifest). The
  * authoritative per-kind manifest validation lives in the kind-specific
  * contracts package and is exercised at boot by the generic
- * `BootstrapContributionsService` template (see
- * `bootstrap-contributions-service.ts`).
- *
- * See `.claude/plans/following-up-the-xema-os-plan-md-abstract-stream.md` §6.C.1.
+ * `BootstrapContributionsService` template.
  */
 export const BiomeContributionEntrySchema = z
   .object({
@@ -268,8 +264,6 @@ export type BiomeContributionEntry = z.infer<typeof BiomeContributionEntrySchema
  * manifest — directory entries are walked first, inline entries layered
  * on top with last-write-wins on `(kind, id)` collision (the host fails
  * fast on duplicates at boot).
- *
- * Phase C plan-of-record: §6.C.1.
  */
 export const BiomeContributionsSchema = z
   .object({
@@ -289,17 +283,13 @@ export type BiomeContributions = z.infer<typeof BiomeContributionsSchema>;
 export const BiomeShipsSchema = z
   .object({
     /**
-     * @deprecated PHASE-C-SWEEP: superseded by top-level
-     * `xema.contributions`. Kept as a free-form string array until the
-     * codemod sweep migrates every biome to the Contribution Protocol.
-     * Values are matched against `ContributionKind` at registration time.
+     * Per-API service declarations. Content contributions (agents, skills,
+     * workflows, deliverable-specs, …) are NOT declared here — they are
+     * discovered by on-disk presence of their convention directory (see
+     * `contentKindToDir`) and/or the `xema.contributions` block. The former
+     * `content` / `modules` string arrays were removed once discovery became
+     * presence-based; do not re-introduce a per-kind declaration.
      */
-    content: z.array(z.string().min(1)).optional(),
-    /**
-     * @deprecated PHASE-C-SWEEP: superseded by top-level
-     * `xema.contributions`. See `content` above — same rationale.
-     */
-    modules: z.array(z.string().min(1)).optional(),
     apis: z.array(BiomeApiDeclarationSchema).optional(),
   })
   .strict();
@@ -414,7 +404,7 @@ export type WebhookFilter = z.infer<typeof WebhookFilterSchema>;
 
 /**
  * Server-side capability declarations. Validated at boot for shape +
- * closed-set membership; runtime enforcement is Phase 4 (network
+ * closed-set membership; runtime enforcement is planned (network
  * allow-list, MCP ACL, secret scope). Declaring intent now means every
  * biome already states it — no migration when enforcement turns on.
  */
@@ -430,7 +420,7 @@ export const ServerBiomeCapabilitiesSchema = z
   .strict();
 export type ServerBiomeCapabilities = z.infer<typeof ServerBiomeCapabilitiesSchema>;
 
-/** Web-side capability declarations. Same Phase-4 timing as server. */
+/** Web-side capability declarations. Same runtime-enforcement timing as server. */
 export const WebBiomeCapabilitiesSchema = z
   .object({
     slots: z.array(z.string().min(1)).optional(),
@@ -500,39 +490,39 @@ const BiomeIdSchema = z
 /**
  * Per-handler declarative event subscription. Type-aliased to
  * `BiomeEventSubscription` so the SDK's manifest field and the
- * `xema-biome.json` parser share one shape. See plan §12.4.
+ * `xema-biome.json` parser share one shape.
  */
 export type BiomeManifestSubscribe = BiomeEventSubscription;
 
 /**
  * `requires`: biome id → semver range. Same shape as the kernel biome
- * manifest's `requires` block (plan §12.4); the platform refuses to
+ * manifest's `requires` block; the platform refuses to
  * enable a biome/biome whose `requires` cannot be satisfied by the
  * other enabled biomes/biomes in the org.
  */
 export type BiomeManifestRequires = Readonly<Record<string, string>>;
 
 /**
- * Additive XSI fields layered onto the per-target `xema` block in Phase
- * 1A (plan §17.2 item 2). Pure additive. All fields are OPTIONAL.
+ * Additive XSI fields layered onto the per-target `xema` block. Pure
+ * additive. All fields are OPTIONAL.
  *
- * - `subscribes[]` — declarative event wiring (§12.4). Each entry binds
+ * - `subscribes[]` — declarative event wiring. Each entry binds
  *   one CloudEvents `type` to a handler module path.
  * - `requires` — typed semver dependency declaration on other
- *   biomes/biomes (§12.4).
+ *   biomes/biomes.
  * - `contributes[]` — closed `ContributionKind` enum from
  *   `@xemahq/kernel-contracts/contribution`. The biome-host uses this to know
- *   which slot registries to walk on install (§12.1).
+ *   which slot registries to walk on install.
  * - `requiresCapabilities[]` — capability refs the biome needs the host
- *   to grant before any of its handlers/contributions execute (§30.2).
+ *   to grant before any of its handlers/contributions execute.
  * - `exposesCapabilities[]` — capability refs the biome itself
- *   implements and offers to others (§30.2).
+ *   implements and offers to others.
  * - `permissions` — install-time consent metadata (default profile +
- *   per-ref hints + UX groupings) for `requiresCapabilities[]` (§30.2).
+ *   per-ref hints + UX groupings) for `requiresCapabilities[]`.
  * - `lifecycle` — module paths the host invokes on
- *   install/upgrade/enable/disable/uninstall transitions (§24.5).
+ *   install/upgrade/enable/disable/uninstall transitions.
  * - `engines.xema` — semver range the host enforces against the running
- *   platform version (§24.4).
+ *   platform version.
  *
  * Kernel-owned types are referenced through the sibling biome contract
  * modules — never redefined here.
@@ -543,11 +533,10 @@ const XsiManifestExtensionsShape = {
   contributes: z.array(ContributionKindSchema).optional(),
   /**
    * Phase-C Contribution Protocol entries (the actual envelopes, not just
-   * the kind whitelist). Replaces the legacy `ships.content` +
-   * `ships.modules` per-kind file-walk seeders with a single generic
-   * `BootstrapContributionsService` template; see Phase C.1 of the
-   * plan-of-record. Either inline entries or a pointer to a
-   * `contributions/` directory at the biome root.
+   * the kind whitelist), fed to a single generic
+   * `BootstrapContributionsService` template. Either inline entries or a
+   * pointer to a `contributions/` directory at the biome root. Complements
+   * the presence-based file-walk seeders (see `contentKindToDir`).
    */
   contributions: BiomeContributionsSchema.optional(),
   requiresCapabilities: z.array(CapabilityRefSchema).optional(),
@@ -733,7 +722,7 @@ const ServerBiomeXemaSchema = z
     ships: BiomeShipsSchema.optional(),
     capabilities: ServerBiomeCapabilitiesSchema.optional(),
     /**
-     * Hosting/provenance posture for adapter-contribution modules (Phase 7).
+     * Hosting/provenance posture for adapter-contribution modules.
      * The same `first-party | third-party` set as {@link BiomeOrigin} (which
      * documents this very field) — uses `BiomeOriginSchema` so the two cannot
      * drift. Other biome kinds ignore this field. Defaults to `third-party`.
@@ -883,14 +872,14 @@ const ServerBiomeXemaSchema = z
       .max(64)
       .optional(),
     /**
-     * Explicit roster of agents this biome ships. Required when
-     * `ships.content` includes `'agents'`; forbidden otherwise. Each
-     * entry pins one `agents/<slug>.md` file with its execution mode
-     * (primary vs subagent).
+     * Explicit roster of agents this biome ships. Present ⟺ the biome has an
+     * on-disk `agents/` directory (discovered by presence). Each entry pins
+     * one `agents/<slug>.md` file with its execution mode (primary vs
+     * subagent).
      *
      * Why both this field AND the on-disk `agents/` scan exist:
      *   - The declaration makes the roster greppable from outside the
-     *     biome tree (`grep '"slug": "build"' biomes/*\/xema-biome.json`).
+     *     biome tree by scanning each biome's `xema-biome.json`.
      *   - It lets biome-host fail fast at boot when an agent file is
      *     added or removed without updating the manifest — the prior
      *     convention silently accepted drift.
@@ -904,10 +893,10 @@ const ServerBiomeXemaSchema = z
      */
     agents: z.array(BiomeAgentDeclarationSchema).optional(),
     /**
-     * Workspace-provisioning scaffolds the biome ships (Epic A). Each
+     * Workspace-provisioning scaffolds the biome ships. Each
      * entry pins one `provisioning/<id>.yaml` recipe and declares when it
-     * runs + how the resolver expands it. Required ⟺ `ships.content`
-     * includes `provisioningScaffolds`; cross-validated in `superRefine`.
+     * runs + how the resolver expands it. Present ⟺ the biome has an on-disk
+     * `provisioning/` directory (discovered by presence).
      */
     provisioning: z.array(ProvisioningScaffoldDeclarationSchema).optional(),
     /**
@@ -916,7 +905,7 @@ const ServerBiomeXemaSchema = z
      * injects the org database identifiers into the runtime workload env.
      */
     database: BiomeDatabaseDeclarationSchema.optional(),
-    /** Reserved for Phase 4 third-party signing. Validated only when present. */
+    /** Reserved for planned third-party signing. Validated only when present. */
     signature: z
       .object({
         algorithm: z.string().min(1),
@@ -925,15 +914,14 @@ const ServerBiomeXemaSchema = z
       })
       .strict()
       .optional(),
-    // XSI Phase 1A additive fields. See `XsiManifestExtensionsShape`
-    // doc-comment above for the per-field meaning + plan citations.
+    // XSI additive fields. See `XsiManifestExtensionsShape`
+    // doc-comment above for the per-field meaning.
     ...XsiManifestExtensionsShape,
   })
   .strict()
   .superRefine((value, ctx) => {
     validateServerPluginWebhookAndIntegrationRequirements(value, ctx);
     validateServerBiomeAgentDeclarations(value, ctx);
-    validateServerPluginProvisioningDeclarations(value, ctx);
   });
 
 const WebBiomeXemaSchema = z
@@ -978,7 +966,7 @@ const WebBiomeXemaSchema = z
       })
       .strict()
       .optional(),
-    // XSI Phase 1A additive fields — same shape on both targets so the
+    // XSI additive fields — same shape on both targets so the
     // biome-host can read them uniformly regardless of where the biome
     // executes. See `XsiManifestExtensionsShape` above.
     ...XsiManifestExtensionsShape,
@@ -1008,41 +996,23 @@ function validateServerPluginWebhookAndIntegrationRequirements(
       });
     }
   }
-  if (value.integrationRequirements && value.integrationRequirements.length > 0) {
-    const shipsInstallSchema = value.ships?.content?.includes('biomeInstallSchema') ?? false;
-    if (!shipsInstallSchema) {
-      ctx.addIssue({
-        code: 'custom',
-        path: ['ships', 'content'],
-        message:
-          'biomes declaring integrationRequirements must also ship a `biomeInstallSchema` content kind so the install wizard can render a resource-selection form',
-      });
-    }
-  }
+  // A biome declaring integrationRequirements must also ship a
+  // `biomeInstallSchema` (the `install-schema/` convention directory) so the
+  // install wizard can render a resource-selection form. That directory is
+  // discovered by on-disk presence; the schema validator has no filesystem
+  // access, so this is enforced at boot-time seeding rather than at
+  // manifest-parse time (there is no longer a `ships.content` list to check).
 }
 
 function validateServerBiomeAgentDeclarations(
   value: ServerBiomeXema,
   ctx: z.RefinementCtx,
 ): void {
-  const shipsAgents = value.ships?.content?.includes('agents') ?? false;
+  // The `agents[]` roster is the authoritative declaration of what a biome
+  // ships; boot-time `crossValidateAgentDeclarations` enforces parity with the
+  // on-disk `agents/*.md` files. Here we only enforce slug uniqueness — there
+  // is no longer a `ships.content` list to cross-check the block against.
   const hasAgents = (value.agents?.length ?? 0) > 0;
-  if (shipsAgents && !hasAgents) {
-    ctx.addIssue({
-      code: 'custom',
-      path: ['agents'],
-      message:
-        'ships.content includes "agents" — manifest must declare each shipped agent under `agents[]` (slug + mode). The boot-time cross-validator enforces parity with on-disk agents/*.md files.',
-    });
-  }
-  if (!shipsAgents && hasAgents) {
-    ctx.addIssue({
-      code: 'custom',
-      path: ['agents'],
-      message:
-        'agents[] is declared but ships.content does not include "agents" — add "agents" to ships.content or remove the agents[] block',
-    });
-  }
   if (hasAgents) {
     const slugs = new Set<string>();
     value.agents?.forEach((decl, idx) => {
@@ -1058,30 +1028,6 @@ function validateServerBiomeAgentDeclarations(
   }
 }
 
-function validateServerPluginProvisioningDeclarations(
-  value: ServerBiomeXema,
-  ctx: z.RefinementCtx,
-): void {
-  const shipsProvisioning = value.ships?.content?.includes('provisioningScaffolds') ?? false;
-  const hasProvisioning = (value.provisioning?.length ?? 0) > 0;
-  if (shipsProvisioning && !hasProvisioning) {
-    ctx.addIssue({
-      code: 'custom',
-      path: ['provisioning'],
-      message:
-        'ships.content includes "provisioningScaffolds" — manifest must declare each scaffold under `provisioning[]`',
-    });
-  }
-  if (!shipsProvisioning && hasProvisioning) {
-    ctx.addIssue({
-      code: 'custom',
-      path: ['provisioning'],
-      message:
-        'provisioning[] is declared but ships.content does not include "provisioningScaffolds" — add it or remove the provisioning[] block',
-    });
-  }
-}
-
 const ManifestNameSchema = z
   .string()
   .min(1)

package/src/biome/lib/biome-permissions.ts

@@ -10,9 +10,9 @@ import {
 
 /**
  * `BiomePermissionsManifest` — the optional `permissions` block of the
- * biome manifest (plan §30.2). It carries:
+ * biome manifest. It carries:
  *
- * - `defaultProfile`: the built-in `BiomePermissionProfile` (plan §30.3)
+ * - `defaultProfile`: the built-in `BiomePermissionProfile`
  *   the install UI suggests by default. Third-party biomes MUST NOT
  *   define new profiles — those are kernel-shipped or org-custom only.
  * - `hints`: one entry per declared `requiresCapabilities[]` ref. The

package/src/biome/lib/biome-scope.ts

@@ -2,9 +2,9 @@ import { z } from 'zod';
 
 /**
  * `BiomeScope` is the closed set of installation scopes a biome may live
- * in (plan §4). A biome installed twice — once in `Org` and once in
+ * in. A biome installed twice — once in `Org` and once in
  * `Sandbox` — is two installations with disjoint state (storage,
- * grants, audit lineage) per §25.2.
+ * grants, audit lineage).
  *
  * String values match the on-wire representation used by
  * `biome-host-api` install records and Object Registry projections.

package/src/biome/lib/biome-trust-tier.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 
 /**
  * `BiomeTrustTier` is the closed set of provenance tiers a biome may
- * carry (plan §21 OQ6). The tier is set at biome publication / install
+ * carry. The tier is set at biome publication / install
  * time and is the primary input to the trust-tier default capability
  * policy (see `trust-tier-policies.ts`).
  *

package/src/biome/lib/trust-tier-policies.ts

@@ -1,7 +1,7 @@
 import { BiomeTrustTier } from './biome-trust-tier';
 
 /**
- * Default capability-policy summary per `BiomeTrustTier` (plan §21 OQ6).
+ * Default capability-policy summary per `BiomeTrustTier`.
  *
  * This table is NOT the authorization decision — `authorization-api` is
  * the source of truth at runtime. It is the kernel-shipped default that
@@ -20,7 +20,7 @@ import { BiomeTrustTier } from './biome-trust-tier';
  *   defaults to `requiresApproval=true` on the corresponding capability
  *   call (`biome:install@1`, `biome:promote@1`).
  * - `allowedEnvironments`: the environment slugs the tier may live in by default —
- *   one of the eight built-in zones declared in plan §3.4
+ *   one of the eight built-in zones
  *   (`system | org | project | app | session | sandbox | public |
  *   store-review`). Org admins may relax or tighten this through
  *   custom policy; the kernel default is the conservative baseline.

package/src/biome-availability/lib/biome-availability.ts

@@ -6,7 +6,7 @@
 // This is a POST-SCOPE FILTER applied AFTER implicit-by-scope resolution
 // (the 5-tier `SkillSpace`/`AgentSpace` precedence): it NARROWS the
 // already-visible set; it never widens it and it is NOT a parallel
-// availability/binding table (see `.claude/rules/skills-and-composition.md`).
+// availability/binding table.
 //
 // Why a filter and not a binding table: the ownership model is implicit-by-
 // scope — a contribution is available because its owning biome is installed

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

@@ -7,8 +7,8 @@ import {
 } from './permission-profile';
 
 /**
- * Manifest shape carried by every `ContributionKind.Capability` envelope
- * (plan §6.H#2). One contribution = one capability ref.
+ * Manifest shape carried by every `ContributionKind.Capability` envelope.
+ * One contribution = one capability ref.
  *
  * The shape is intentionally a value-identical subset of
  * `RegisterCapabilityDto` (the `POST /capabilities/register` body shape on
@@ -52,7 +52,7 @@ export interface CapabilityContributionManifest {
   /**
    * Identifier of the EXTERNAL service this capability calls (e.g. a provider
    * slug like `github` or an MCP server ref). Presence is the signal that the
-   * invocation needs a brokered external credential (plan §W4 / Pillar 3.2):
+   * invocation needs a brokered external credential:
    * authorization-api runs the credential-binding precedence ladder ONLY for
    * capabilities that declare it, and the executing gateway resolves a sealed
    * credential for that service. Absent ⇒ the capability is internal and needs

package/src/capability/lib/capability-grant.ts

@@ -35,7 +35,7 @@ export type { SubjectRef, ActingForRef };
 /**
  * Per-grant runtime caps. None of these are required at the contract level;
  * absent fields mean "no platform-imposed limit on this axis". Profiles
- * (§30.3) may default some of them; admins may tighten or loosen per row.
+ * may default some of them; admins may tighten or loosen per row.
  */
 export interface GrantConstraints {
   maxCallsPerHour?: number;
@@ -55,14 +55,14 @@ export const GrantConstraintsSchema = z.object({
 }) as z.ZodType<GrantConstraints>;
 
 /**
- * `CapabilityGrant` is the single row shape `authorization-api` stores
- * (per §3.4, §30.5). One grant binds ONE `(subject, capability)` pair to a
+ * `CapabilityGrant` is the single row shape `authorization-api` stores.
+ * One grant binds ONE `(subject, capability)` pair to a
  * `resourceGlob`, an allowed-environment set, and optional runtime constraints.
  *
  * Wildcards (`kb:*@1`) are NOT represented in `capability` at the contract
  * level — the kernel grammar in `capability-ref.ts` rejects them. Wildcard
  * grants are stored as multiple per-verb rows OR as a separate
- * domain-wildcard table in `authorization-api`; the choice is a Phase 3
+ * domain-wildcard table in `authorization-api`; the choice is an
  * implementation detail, not a kernel concern.
  */
 export interface CapabilityGrant {
@@ -71,7 +71,7 @@ export interface CapabilityGrant {
   capability: CapabilityRef;
   /**
    * Glob over XVFS resource refs, e.g. `xema://org/acme/project/*\/kb/**`.
-   * Authorization-api owns glob semantics (§30.4).
+   * Authorization-api owns glob semantics.
    */
   resourceGlob: string;
   allowedEnvironments: readonly string[];

package/src/capability/lib/capability-policy.ts

@@ -10,8 +10,8 @@ export { GrantConstraintsSchema } from './capability-grant';
 
 /**
  * `CapabilityPolicy` is what an `ExecutionEnvironment` carries to advertise the
- * capability surface allowed *within* that environment (plan §3.4
- * `ExecutionEnvironment.allowedCapabilities[]`).
+ * capability surface allowed *within* that environment
+ * (`ExecutionEnvironment.allowedCapabilities[]`).
  *
  * A environment's policy is a NECESSARY-but-not-sufficient condition for a runtime
  * call: the environment allows the capability AND the subject has a matching

package/src/capability/lib/capability-ref.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { CapabilityRefParseError } from './errors';
 
 /**
- * Canonical Capability Reference grammar (plan §3.3):
+ * Canonical Capability Reference grammar:
  *
  *   `<domain>:<resource>.<verb>@<major>`
  *
@@ -12,14 +12,14 @@ import { CapabilityRefParseError } from './errors';
  * - `<domain>` and the first `<resource>` segment match
  *   `/^[a-z][a-z0-9-]*$/` (kebab, must start with a letter).
  * - The `<resource>.<verb>` portion is one OR MORE `.`-joined kebab segments
- *   (each segment matches the same shape as `<domain>`). This permits the
- *   examples in the plan such as `kb:page.read@1`, `connector:scm.merge@1`,
+ *   (each segment matches the same shape as `<domain>`). This permits
+ *   examples such as `kb:page.read@1`, `connector:scm.merge@1`,
  *   `document:render.pdf@1`, `connector:tracker.issue.create@1`, AND
  *   nested forms such as `model-resolution:select@1` (single segment after
  *   `:`, where the segment IS the verb on the implicit resource).
  * - `<major>` is one or more digits (no leading sign, no float). The major
  *   version is part of the ref itself — capability refs version like
- *   syscalls per §3.3.
+ *   syscalls.
  *
  * Invariants enforced by `parseCapabilityRef` / `CapabilityRefSchema`:
  *

package/src/capability/lib/errors.ts

@@ -7,12 +7,10 @@ import { z } from 'zod';
  * so callers can branch structurally (no string parsing). The set covers:
  *   - parse-time failures on `CapabilityRef`;
  *   - resolution failures when no contribution implements the ref;
- *   - the four distinct denial axes specified in §3.4 + §30.5
+ *   - the four distinct denial axes
  *     (environment, grant, rate-limit, human-approval);
  *   - the "you do not even have a grant row" case that drives `xema why-denied`
- *     suggestion `request-grant` (§31.8).
- *
- * Plan-of-record references: §3.3, §30.5, §31.8.
+ *     suggestion `request-grant`.
  */
 export enum CapabilityErrorCode {
   CapabilityRefInvalid = 'CAPABILITY_REF_INVALID',
@@ -25,7 +23,7 @@ export enum CapabilityErrorCode {
   AuthorizationUnreachable = 'AUTHORIZATION_UNREACHABLE',
   /**
    * The invocation passed authorization but its mandatory audit record
-   * could not be persisted after retries (Gate E). The gateway refuses the
+   * could not be persisted after retries. The gateway refuses the
    * invocation rather than completing it without an audit trail — surfaced
    * as a 503 so the caller can retry (the audit write is idempotent on
    * `auditId`). This is the fail-fast path for the audit sink; it is NEVER
@@ -52,7 +50,7 @@ export enum CapabilityErrorCode {
    * `externalServiceRef`), but authorization-api's credential-binding
    * precedence resolved no permitted binding for this invocation — no explicit
    * grant binding, no capability-descriptor default, and no project/org
-   * default. Fail-fast (plan §W4 / Pillar 3.2): the PDP returns `deny` with
+   * default. Fail-fast: the PDP returns `deny` with
    * this code rather than letting the invocation run credential-less or letting
    * a gateway silently pick a credential. The broker NEVER chooses a binding;
    * the PDP is the single authority.
@@ -66,8 +64,6 @@ export const CapabilityErrorCodeSchema = z.nativeEnum(CapabilityErrorCode);
  * Discriminated "why" structure for a denial decision. One denial may carry
  * multiple `CapabilityDenialDetail` entries (e.g. the grant exists but the
  * resource glob does not match AND the rate-limit is exhausted).
- *
- * Plan-of-record reference: §31.8.
  */
 export interface CapabilityDenialDetail {
   code: CapabilityErrorCode;
@@ -83,8 +79,6 @@ export const CapabilityDenialDetailSchema = z.object({
  * Suggestions the Capability Gateway returns so an agent (or a human via
  * `xema why-denied`) can self-correct without trial-and-error.
  *
- * Plan-of-record reference: §31.8.
- *
  * The discriminator `kind` is a closed set; do NOT widen with free-form
  * strings.
  */

package/src/capability/lib/meta-tool.ts

@@ -3,14 +3,11 @@ import { z } from 'zod';
 import { CapabilityRefSchema, type CapabilityRef } from './capability-ref';
 
 /**
- * Xema OS Phase H — the agent-facing MCP surface collapses to exactly three
+ * The agent-facing MCP surface collapses to exactly three
  * meta-tools. The set is CLOSED — no free-form strings — so we ship the
  * canonical names as a kernel enum that the router controller, the
  * mcp-gateway federation bridge, and any downstream client can all agree on.
  *
- * Plan-of-record:
- *   `.claude/plans/following-up-the-xema-os-plan-md-abstract-stream.md` §6.H
- *
  * The string values are the wire names emitted to OpenCode via the
  * mcp-gateway federation bridge (`resolveAsMetaTools()`). They are also the
  * suffix segments of the router HTTP routes:
@@ -28,7 +25,7 @@ export enum MetaToolName {
 export const MetaToolNameSchema = z.nativeEnum(MetaToolName);
 
 /**
- * Wire-side audit topic for every meta-tool invocation (Phase H.5). Kept here
+ * Wire-side audit topic for every meta-tool invocation. Kept here
  * — not in a service — so analytics consumers and the router emit the same
  * string.
  */

package/src/capability/lib/permission-profile.ts

@@ -2,12 +2,12 @@ import { z } from 'zod';
 import { CapabilityRefSchema, type CapabilityRef } from './capability-ref';
 
 /**
- * Closed set of built-in permission **Profiles** shipped by the kernel
- * (plan §30.3). Profiles are pre-canned `GrantPolicy` templates that an
+ * Closed set of built-in permission **Profiles** shipped by the kernel.
+ * Profiles are pre-canned `GrantPolicy` templates that an
  * org admin can apply with one click at biome install time.
  *
  * Third-party biomes MUST NOT add profiles (would be a privilege-escalation
- * vector — §30.3). Orgs may add **Custom Profiles** stored in
+ * vector). Orgs may add **Custom Profiles** stored in
  * `authorization-api`, but those are runtime data, not kernel enum values.
  *
  * String values are kebab-case so they match the on-wire / on-disk
@@ -32,7 +32,7 @@ export const BiomePermissionProfileSchema = z.nativeEnum(
 
 /**
  * Risk tier of a single capability ask, declared by the biome author in
- * the manifest (plan §30.1, §30.2). Drives the install-time digest and
+ * the manifest. Drives the install-time digest and
  * default approval requirements (`critical` always requires explicit
  * approval, regardless of profile).
  */
@@ -47,7 +47,7 @@ export const CapabilityRiskTierSchema = z.nativeEnum(CapabilityRiskTier);
 
 /**
  * `PermissionHint` — one entry per declared `requiresCapabilities[]` ref
- * in the biome manifest's `permissions.hints[]` block (plan §30.2).
+ * in the biome manifest's `permissions.hints[]` block.
  *
  * The hint is author-facing copy that drives the install-time digest UI;
  * it does NOT itself grant anything. The grant materialises only when the
@@ -76,8 +76,8 @@ export const PermissionHintSchema = z.object({
 
 /**
  * `PermissionGroup` — author-side bundling of related capabilities so the
- * install UI can render "Grant the *kb-read* group" as one toggle
- * (plan §30.2). Grants are still recorded per-capability in
+ * install UI can render "Grant the *kb-read* group" as one toggle.
+ * Grants are still recorded per-capability in
  * `authorization-api`; the group is pure UX sugar.
  */
 export interface PermissionGroup {