@xemahq/kernel-contracts 0.22.3 → 0.23.1

package/src/object/lib/xema-object-kind.ts

@@ -66,7 +66,7 @@ export enum XemaObjectKind {
   // Contribution registry (self-referential)
   ContributionEntry = 'contribution-entry',
 
-  // Concept registry — self-describing OS documentation objects (§31.3)
+  // Concept registry — self-describing OS documentation objects
   Concept = 'concept',
 }
 

package/src/object/lib/xema-object-ref.ts

@@ -3,8 +3,8 @@ import { SpaceRef, SpaceKind, spaceRefToPath } from '../../space';
 import { XemaObjectKind, XemaObjectKindSchema } from './xema-object-kind';
 
 /**
- * Stable wire shape for every XemaObject address (XSI plane 1, §3.1 +
- * §6.1 of the plan-of-record). The grammar is:
+ * Stable wire shape for every XemaObject address (XSI plane 1). The
+ * grammar is:
  *
  *   `xema://<scope-path>/<kind>/<slug>[@<version>]`
  *

package/src/org-database/lib/db-result-event.ts

@@ -30,12 +30,12 @@ export interface DbColumnMeta {
 
 /**
  * Surface event payload emitted when the database explorer executes a SQL
- * statement on behalf of an agent tool call. Mirrors plan §12.4 verbatim.
+ * statement on behalf of an agent tool call.
  *
  * `rows` carries the actual row data — it MUST go to the frontend only and
  * MUST never be passed back into LLM context. Producers route it through
- * the agent-session SSE channel (in H5+) or return it inline to the
- * caller (in H1, when no SSE bridge exists yet).
+ * the agent-session SSE channel where available, or return it inline to the
+ * caller when no SSE bridge exists yet.
  *
  * `statement` is the SQL string the agent supplied. It is shown in the UI
  * as a reference for the user; it is NOT a secret. Audit logs hash the

package/src/policy/lib/obligations.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { DataClassificationSchema } from '../../space';
 
 /**
- * Closed obligation taxonomy (plan v4.3 §A.4).
+ * Closed obligation taxonomy.
  *
  * Every `PolicyObligation` carries one of these `kind` discriminants;
  * the wire payload is a discriminated union (see `PolicyObligation`).
@@ -33,8 +33,7 @@ export const PolicyObligationKindSchema = z.nativeEnum(PolicyObligationKind);
 
 /**
  * Closed runner-kind set referenced by `PolicyObligation`
- * (`require-runner-kind`) and by `RouteHint.preferredRunnerKind` (plan
- * v4.3 §2 / §A.4).
+ * (`require-runner-kind`) and by `RouteHint.preferredRunnerKind`.
  *
  * This is the canonical `RunnerKind` — the policy decision layer is its
  * primary author (policy selects on it to route an invocation), so it lives
@@ -50,7 +49,7 @@ export enum RunnerKind {
   Sandbox = 'sandbox',
   CI = 'ci',
   /**
-   * Phase H.3 — external MCP server bridged through `mcp-gateway-api`'s
+   * External MCP server bridged through `mcp-gateway-api`'s
    * external-bridge. The router resolves capability refs of the form
    * `<provider-slug>:<tool-name>@1` to this runner kind, then forwards
    * the invoke envelope to the bridge which translates back to an MCP
@@ -63,7 +62,7 @@ export const RunnerKindSchema = z.nativeEnum(RunnerKind);
 
 /**
  * Closed data-residency tag set referenced by `PolicyObligation`
- * (`data-residency`) (plan v4.3 §A.4).
+ * (`data-residency`).
  *
  * `customer-private` is the customer-edge tenancy class used when the
  * org runs its own runner in a private network. Add new regions by
@@ -195,7 +194,7 @@ export type EgressAllowlistObligation = z.infer<
 >;
 
 /**
- * `PolicyObligation` — closed discriminated union (plan v4.3 §A.4).
+ * `PolicyObligation` — closed discriminated union.
  *
  * Producers MUST construct one of the typed variants above; consumers
  * MUST switch on `kind` and handle every variant explicitly. The kernel

package/src/policy/lib/policy.ts

@@ -10,11 +10,11 @@ import {
 import { RouteHintSchema, type RouteHint } from './route-hints';
 
 /**
- * Closed decision set (plan v4.3 §A.4).
+ * Closed decision set.
  *
  * `needs_approval` is its own outcome — never collapsed into `allow`
  * with an obligation; the router suspends the invocation when it sees
- * this kind and emits `approval.requested.v1` (plan §A.5).
+ * this kind and emits `approval.requested.v1`.
  */
 export enum PolicyDecisionKind {
   Allow = 'allow',
@@ -26,7 +26,7 @@ export const PolicyDecisionKindSchema = z.nativeEnum(PolicyDecisionKind);
 
 /**
  * Which precedence tier supplied the `credentialBindingId` on an `allow`
- * decision (plan §W4 / Pillar 3.2). Closed set — the PDP applies a fixed
+ * decision. Closed set — the PDP applies a fixed
  * priority ladder and records the winning tier so the Studio debugger (and
  * audit) can explain WHY a given binding was selected, without re-deriving it.
  *
@@ -47,7 +47,7 @@ export enum CredentialPrecedenceSource {
    * A deployment-wide platform default provision (broadest tier, below org).
    * An org-scoped default always overrides it. Used by `authorization-api`'s
    * credential-precedence resolver once this kernel change is published +
-   * consumed (see the Connections framework plan).
+   * consumed.
    */
   PlatformDefault = 'platform_default',
 }
@@ -58,7 +58,7 @@ export const CredentialPrecedenceSourceSchema = z.nativeEnum(
 
 /**
  * `PolicyRequest` — the input shape `authorization-api.policyCheck`
- * accepts (plan v4.3 §A.4).
+ * accepts.
  *
  * Currently a type alias for `ExecutionContext` because every field
  * policy needs is already on the envelope. Kept as a separate name so a
@@ -72,7 +72,7 @@ export const PolicyRequestSchema: z.ZodType<PolicyRequest> =
 
 /**
  * `PolicyDecision` — the output shape `authorization-api.policyCheck`
- * returns (plan v4.3 §A.4).
+ * returns.
  *
  * `kind` is the verdict; `obligations` is a CLOSED discriminated union
  * (see `PolicyObligation`); `routeHints` carries runner-selection
@@ -86,7 +86,7 @@ export interface PolicyDecision {
   routeHints?: RouteHint;
   /**
    * The credential binding the executing gateway MUST use to resolve the
-   * external credential for this invocation (plan §W4 / Pillar 3.2). Present
+   * external credential for this invocation. Present
    * ONLY on an `allow` decision for a capability that declares an
    * `externalServiceRef`. The PDP is the single authority that selects it via
    * the deterministic precedence ladder; the router passes ONLY this opaque id

package/src/policy/lib/route-hints.ts

@@ -3,7 +3,7 @@ import { RunnerKind, RunnerKindSchema } from './obligations';
 
 /**
  * `RouteHint` — runner-selection guidance emitted alongside a
- * `PolicyDecision` (plan v4.3 §A.4).
+ * `PolicyDecision`.
  *
  * The capability router consults this AFTER policy returns `allow`, to
  * pick a runner that satisfies all hints. Hints are PREFERENCES unless

package/src/provisioning/index.ts

@@ -1,7 +1,7 @@
 // ═══════════════════════════════════════════════════════════════════════════
 // @xemahq/provisioning-contracts — Workspace Provisioning wire contracts.
 //
-// Pure types + Zod schemas for the `provision` lifecycle phase (Epic A): the
+// Pure types + Zod schemas for the `provision` lifecycle phase: the
 // deterministic, guard-gated `SCAFFOLD` / `EQUIP` steps that prepare a
 // session's repo content. agent-session-api's `provisioning-plan-resolver`
 // RESOLVES a plan from biome manifests; workspace-proxy's

package/src/provisioning/lib/provisioning.ts

@@ -140,7 +140,7 @@ export type ProvisioningAgentInstruction = z.infer<
 >;
 
 /**
- * Presigned-URL pair for the content-addressed scaffold cache (Epic A §A4).
+ * Presigned-URL pair for the content-addressed scaffold cache.
  * agent-session-api mints these from a step's `cacheKey`; workspace-proxy
  * GETs `getUrl` to probe for a hit, and on a miss PUTs the built tar to
  * `putUrl` (write-through). `getHeaders` / `putHeaders` are the headers the
@@ -194,7 +194,7 @@ export const ResolvedProvisioningStepSchema = z
     targetDir: z.string().min(1),
     cacheKey: z.string().min(1).nullable(),
     /**
-     * Presigned scaffold-cache URLs derived from `cacheKey` (Epic A §A4).
+     * Presigned scaffold-cache URLs derived from `cacheKey`.
      * Present only on a cacheable step whose URLs were minted at resolve
      * time; absent ⇒ the executor builds locally with no cache.
      */
@@ -231,7 +231,7 @@ export type ResolvedProvisioningPlan = z.infer<
  * A `built` step that had a `cache` ref and is eligible for an out-of-band
  * cache write. The executor no longer writes the cache inline; instead it
  * surfaces the pending write here, and the caller (agent-session-api)
- * dispatches `writeScaffoldCacheWorkflow` per entry (Phase J §J3).
+ * dispatches `writeScaffoldCacheWorkflow` per entry.
  *
  * `cacheRef` is the SAME ref the plan carried in — re-passed to keep the
  * activity stateless (workspace-proxy doesn't have to retain a presigned
@@ -257,7 +257,7 @@ export const ProvisioningStepResultSchema = z
     /**
      * Non-empty only on a `built` step whose plan carried a `cache` ref.
      * The caller dispatches `writeScaffoldCacheWorkflow` per entry — the
-     * executor never writes the cache itself (Phase J §J3).
+     * executor never writes the cache itself.
      */
     pendingCacheWrite: ProvisioningPendingCacheWriteSchema.optional(),
   })

package/src/resource/lib/resource-ownership-contribution.ts

@@ -19,7 +19,7 @@ const RESOURCE_PRINCIPALS_MAX = 100;
 
 /**
  * `ResourceVisibilityPattern` — the closed set of ownership/visibility shapes a
- * biome may declare for a resource instance it contributes (plan §6 Phase 5).
+ * biome may declare for a resource instance it contributes.
  *
  * Precedence is NOT encoded here — this enum only names HOW a resource is
  * shared; the PDP in `authorization-api` derives the effective verdict from the
@@ -78,7 +78,7 @@ export const ExplicitShareRefSchema: z.ZodType<ExplicitShareRef> = z.object({
 
 /**
  * Manifest shape carried by every `ContributionKind.ResourceOwnership`
- * envelope (plan §6 Phase 5). One contribution = one resource instance's
+ * envelope. One contribution = one resource instance's
  * ownership/visibility declaration.
  *
  * Mirrors `CapabilityContributionManifest` precisely: a value-identical subset

package/src/runner/lib/dispatch.ts

@@ -5,8 +5,8 @@ import {
 } from '../../execution-context';
 
 /**
- * CloudEvent type emitted on the dispatch fan-out channel (Phase F.3
- * Push transport). Pull-mode runners receive the same envelope as the
+ * CloudEvent type emitted on the dispatch fan-out channel (Push
+ * transport). Pull-mode runners receive the same envelope as the
  * body of `POST /runners/<id>/pull-work`.
  *
  * Constant, not enum — there is exactly one dispatch type today.
@@ -16,13 +16,13 @@ import {
 export const RUNNER_DISPATCH_CLOUDEVENT_TYPE = 'xema.runner.dispatch.v1' as const;
 
 /**
- * `RunnerDispatch` (Phase F.3) — superset of the legacy
+ * `RunnerDispatch` — superset of the legacy
  * `RunnerJobDispatch` shape. This v1 envelope carries the full
  * `ExecutionContext` so the runner can re-validate the policy decision
  * locally before invoking the capability.
  *
  * `tokenJwt` is the compact-JWS form of the RS256 `JobToken` minted by
- * the kernel-server (Phase F.5), aligned with `RunnerJobDispatch.tokenJwt`.
+ * the kernel-server, aligned with `RunnerJobDispatch.tokenJwt`.
  * The runner MUST verify the signature + claims against the kernel-server
  * JWKS before touching the dispatch.
  */
@@ -33,7 +33,7 @@ export interface RunnerDispatch {
   executionContext: ExecutionContext;
   /**
    * The capability invocation input, carried by value so the runner has the
-   * actual arguments to execute with (Phase F.7). The `ExecutionContext`
+   * actual arguments to execute with. The `ExecutionContext`
    * carries only an `inputHash` fingerprint — not the payload — so without
    * this field the runner could verify identity but had nothing to run.
    *

package/src/runner/lib/job-token.ts

@@ -1,7 +1,7 @@
 import type { RunnerId } from './runner';
 
 /**
- * Signed job token (plan §6 Phase F.5).
+ * Signed job token.
  *
  * Kernel-server mints an RS256 token with a hard ceiling of 60 seconds
  * per invocation. The runner MUST verify signature + scope before
@@ -37,7 +37,7 @@ export interface JobToken {
   subjectId: string;
   /**
    * `canonicalCapabilityInputHash` of the dispatched invocation input
-   * (Phase F.7). Binds the unsigned `RunnerDispatch.input` to this signed
+   * Binds the unsigned `RunnerDispatch.input` to this signed
    * token so the runner can detect input tampering before executing.
    */
   inputHash: string;

package/src/runner/lib/runner-attestation.ts

@@ -12,14 +12,14 @@ export const RUNNER_ATTESTATION_REJECTED_CLOUDEVENT_TYPE =
   'xema.runner.attestation.rejected.v1' as const;
 
 /**
- * Runner attestation (plan §6 Phase F.4).
+ * Runner attestation.
  *
  * Carried by a runner on every `register` against the kernel-server.
  * The kernel-server validates:
  * - `identityJwt` is signed by the trusted Keycloak realm and the
  *   subject is a service-account claim of kind `runner`.
  * - `allowedEnvironments` is countersigned by an org-admin role
- *   (validated via OpenFGA / OPA — see Phase D).
+ *   (validated via OpenFGA / OPA).
  * - `signedAt` is within the configured attestation freshness window.
  *
  * Any validation failure is fail-fast — the runner is rejected and the

package/src/runner/lib/runner-job.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 /**
- * `RunnerJob` lifecycle state machine (plan §6 Phase F.7).
+ * `RunnerJob` lifecycle state machine.
  *
  *   Pending → Dispatched → Accepted → Running → Succeeded (terminal)
  *                                            ↘ Failed     (terminal)
@@ -64,7 +64,7 @@ export const RUNNER_JOB_COMPLETED_CLOUDEVENT_TYPE =
 
 /**
  * Report-back envelope a runner emits on accept / progress / completion
- * (Phase F.7). `workload-runtime` keys idempotent state transitions on
+ * `workload-runtime` keys idempotent state transitions on
  * `(jobId, state)`; `output` is present only on a `Succeeded` report and
  * `error` only on a `Failed` report.
  */

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

@@ -1,5 +1,5 @@
 /**
- * Runner transport mode (plan §6 Phase F.3).
+ * Runner transport mode.
  *
  * - `Push` (cluster default) — kernel-server emits
  *   `xema.runner.dispatch.v1` CloudEvent; runner consumes via

package/src/runner/lib/runner-plane.ts

@@ -1,5 +1,5 @@
 /**
- * Runner-plane registry conventions (plan §6 Phase F.6).
+ * Runner-plane registry conventions.
  *
  * Runners do not have a bespoke registry; they publish ordinary
  * `ServiceDescriptor`s to the Service Registry under ONE well-known
@@ -11,7 +11,7 @@
  * the `ServiceDescriptor` type is in scope).
  *
  * Keeping the name + label keys here — in the kernel leaf both the
- * runner producers (Phase F.3/F.5) and the router selector consume —
+ * runner producers and the router selector consume —
  * guarantees producer/consumer agreement without a second contracts
  * package. Adding/renaming a key is a coordinated kernel change.
  */

package/src/runner/lib/runner-registration.ts

@@ -5,8 +5,7 @@ import { RunnerTransportMode } from './runner-mode';
 import { RunnerTrustTier } from './runner';
 
 /**
- * High-level execution mode a runner declares at registration time
- * (plan §6 Phase F, north-star §3 "three biome execution modes").
+ * High-level execution mode a runner declares at registration time.
  *
  * This is the *biome execution mode* (where the biome physically runs)
  * — DISTINCT from `RunnerTransportMode` (push vs pull, how the runner
@@ -17,19 +16,19 @@ import { RunnerTrustTier } from './runner';
  */
 export enum RunnerMode {
   /**
-   * Runs inside `xema-kernel-server` itself — Phase F.1. The kernel
+   * Runs inside `xema-kernel-server` itself. The kernel
    * registers a synthetic runner descriptor under this mode so the
    * dispatcher sees embedded biomes as ordinary registry entries.
    */
   Embedded = 'embedded',
   /**
    * Sidecar process supervised by `biome-host-api`'s local-module
-   * supervisor — Phase F.2. The default for dev + first-party.
+   * supervisor. The default for dev + first-party.
    */
   LocalModule = 'local-module',
   /**
    * Out-of-cluster runner reachable via event-hub Push or long-poll
-   * Pull — Phase F.3.
+   * Pull.
    */
   Remote = 'remote',
 }
@@ -54,7 +53,7 @@ export enum DataLocality {
 export const DataLocalitySchema = z.nativeEnum(DataLocality);
 
 /**
- * Embedded biome registration — Phase F.1.
+ * Embedded biome registration.
  *
  * Lives on a `RunnerRegistration` whose `mode === RunnerMode.Embedded`.
  * The `xema-kernel-server` enumerates its built-in biomes (concept
@@ -152,9 +151,9 @@ export const RunnerHealthcheckSchema = z.object({
 
 /**
  * Top-level registration a runner publishes to the Service Registry at
- * boot (Phase F.3). One row per runner instance; biomes hang underneath.
+ * boot. One row per runner instance; biomes hang underneath.
  *
- * Carry-forwards (Phase F.4/F.5):
+ * Carry-forwards (planned):
  *   - Keycloak service-account JWT validation
  *   - Org-admin-countersigned `allowedEnvironments`
  *   - RS256 signed job tokens with ≤60s TTL
@@ -167,7 +166,7 @@ export interface RunnerRegistration {
   region?: string;
   /**
    * IDs of `ExecutionEnvironment`s this runner is permitted to serve.
-   * Phase F.4 will countersign this list via the Keycloak service
+   * A future step will countersign this list via the Keycloak service
    * account; until then the runner is trusted to declare its own set.
    */
   allowedEnvironments?: string[];
@@ -177,7 +176,7 @@ export interface RunnerRegistration {
    */
   dataLocality?: DataLocality;
   /**
-   * Trust tier assigned at attestation time (Phase F.4). Absent until
+   * Trust tier assigned at attestation time. Absent until
    * the kernel-server attests the runner; the policy bundle MAY gate
    * sensitive capabilities to `Trusted`/`System` tiers only.
    */

package/src/runner/lib/runner.ts

@@ -1,7 +1,7 @@
 import { RunnerKind } from '../../policy';
 
 /**
- * Runner-plane contracts (plan §6 Phase F).
+ * Runner-plane contracts.
  *
  * A runner is the executor that picks up a `RunnerJobDispatch` and
  * actually invokes the capability.
@@ -14,7 +14,7 @@ import { RunnerKind } from '../../policy';
  */
 
 /**
- * Trust tier assigned to a runner at attestation time (Phase F.4). The
+ * Trust tier assigned to a runner at attestation time. The
  * authorization-api's policy bundle MAY gate sensitive capabilities to
  * `Trusted` or `System` tiers only.
  *
@@ -32,8 +32,8 @@ export enum RunnerTrustTier {
 /**
  * Canonical ordinal rank for each {@link RunnerTrustTier}. Higher = more
  * authority. This is the SINGLE source of trust ordering — the router's
- * dispatch min-trust gate (Phase F.4) and the runner's per-capability
- * min-trust gate (Phase F.7) MUST both rank through this map so a runner
+ * dispatch min-trust gate and the runner's per-capability
+ * min-trust gate MUST both rank through this map so a runner
  * the router accepts is ranked identically by the executor. Do not inline a
  * second ordering.
  */
@@ -75,9 +75,9 @@ export type RunnerId = string & { readonly __brand: 'RunnerId' };
 /**
  * Self-description a runner publishes at registration time. Mirrors
  * `ServiceDescriptor` in spirit but carries runner-specific labels
- * (data locality, region) consumed by `Policy.routeHints` (Phase F.6).
+ * (data locality, region) consumed by `Policy.routeHints`.
  *
- * For the richer Phase F.3 registration shape (mode + biome
+ * For the richer registration shape (mode + biome
  * provisioning + transport) see `RunnerRegistration`.
  */
 export interface RunnerDescriptor {
@@ -87,7 +87,7 @@ export interface RunnerDescriptor {
   version: string;
   /**
    * IDs of `ExecutionEnvironment`s this runner is allowed to serve.
-   * The list is signed by the org admin via Phase F.4 attestation; a
+   * The list is signed by the org admin via attestation; a
    * runner MUST refuse a dispatch whose `executionContext.environmentId`
    * is not in this list.
    */

package/src/runner-input-hash/lib/input-hash.ts

@@ -1,8 +1,8 @@
 import { createHash } from 'node:crypto';
 
 /**
- * Deterministic canonical hash of a capability invocation input (plan §6
- * Phase F.7, input-integrity binding).
+ * Deterministic canonical hash of a capability invocation input
+ * (input-integrity binding).
  *
  * The runner plane separates execution authority: the kernel-server mints
  * the RS256 `JobToken` and the router dispatches the `RunnerDispatch`. Under

package/src/service-registry/lib/service-descriptor.ts

@@ -1,5 +1,5 @@
 /**
- * Service Registry contracts (plan §6 Phase B.1).
+ * Service Registry contracts.
  *
  * The Service Registry is the kernel primitive that replaces the
  * `*_API_URL` env-var hellscape. Every NestJS app at boot registers a

package/src/service-registry/lib/service-names.generated.ts

@@ -1,6 +1,4 @@
-// boundary-check:exempt — this generated file enumerates first-party service
-// names verbatim (e.g. 'opencode-worker'); those names ARE the data, not a
-// tech-stack leak, so the stack-confidentiality scan is opted out here.
+// Canonical first-party service names for the platform.
 // AUTO-GENERATED by tooling/codegen/generate-service-names.mjs — DO NOT EDIT.
 // Source of truth: each biome's xema-biome.json ships.apis[].name + every
 // ServiceRegistryModule descriptor name. Regenerate: `node tooling/codegen/generate-service-names.mjs`.

package/src/space/lib/space-ref-parser.ts

@@ -1,6 +1,6 @@
 import { SpaceKind, type SpaceRef } from './space';
 
-// SpaceRef URI grammar (plan §2 + §6.A.2):
+// SpaceRef URI grammar:
 //
 //   xema://system
 //   xema://org/<org>

package/src/space/lib/space.ts

@@ -1,10 +1,9 @@
 import { z } from 'zod';
 
 /**
- * Closed kind set — Spaces have exactly these 7 layers (plan v4.3 §2/§3
- * vocabulary). Replaces the legacy 5-tier `ScopeTier` (System / Biome /
- * Org / Project / User) by adding `App` and `Session` for the runtime
- * ownership plane introduced in Phase A.2.
+ * Closed kind set — Spaces have exactly these 7 layers. Replaces the
+ * legacy 5-tier `ScopeTier` (System / Biome / Org / Project / User) by
+ * adding `App` and `Session` for the runtime ownership plane.
  *
  * Precedence is **most specific wins**:
  *   User > Session > Biome > App > Project > Org > System
@@ -38,7 +37,7 @@ export enum DataClassification {
  * `orgId` and `projectId`). Optional `path` carries the fully-formatted
  * `xema://...` URI when materialised.
  *
- * Phase A.2 (plan v4.3) — value-identical rename from `ScopeRef`. Field
+ * Value-identical rename from `ScopeRef`. Field
  * names (`tier`, `orgId`, `projectId`, `biomeId`, `userId`) are
  * unchanged so the rename is a single identifier swap at every consumer.
  */

package/src/widget/lib/chat-widget-envelope.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 /**
  * `ChatWidgetEnvelope` — a single widget instance recorded on an assistant
  * message's `metadata.widgets[]` and rendered by the host-web ChatWidget
- * registry (HANDOFF §3.2).
+ * registry.
  *
  * `kind` is a first-party {@link ChatWidgetKind} value OR a namespaced biome
  * string (`<biomeId>:<kind>`). `version` is the monotonic schema version for

package/src/worker-runtime/lib/capabilities.ts

@@ -38,7 +38,7 @@ export interface WorkerRuntimeCapabilityBits {
  * Scheduler-side capability bits. The runtime declares which scheduler
  * features it depends on; the scheduler advertises which it provides. The
  * composer matches the two — a required capability missing on the
- * scheduler is a fail-fast error (per plan §D18: no silent degradation).
+ * scheduler is a fail-fast error (no silent degradation).
  */
 export interface SchedulerCapabilityBits {
   readonly autoRestart: boolean;

package/src/workflow/index.ts

@@ -35,9 +35,8 @@ export * from './lib/briefcase';
 export * from './lib/catalog-taxonomies';
 export * from './lib/domain-tag';
 // Generic ordered-stage contract. The software-delivery-specific stage list,
-// hierarchy, and gate-reviewer map were relocated to the software-dev biome
-// (`biomes/platform/software-dev/workflow-config/phase-config.json`) — the
-// kernel carries no domain phase enum.
+// hierarchy, and gate-reviewer map were relocated to the software-dev biome's
+// workflow config — the kernel carries no domain phase enum.
 export * from './lib/phase-report';
 export * from './lib/work-item-payloads';
 export * from './lib/canonical-concepts';

package/src/workflow/lib/activity-outputs.ts

@@ -17,10 +17,9 @@
 // output was conditionally absent).
 //
 // Activity authors do NOT construct ArtifactRefs themselves. They pass
-// content + type to the `finalizeOutputs` helper (in
-// `biomes/workflow-runtime/api/workflow-runtime-worker/src/activities/shared/finalize-outputs.ts`)
-// which promotes content to artifacts via `workflow-artifact-emitter` and
-// replaces the values with refs.
+// content + type to the `finalizeOutputs` helper, which promotes content
+// to artifacts via `workflow-artifact-emitter` and replaces the values
+// with refs.
 //
 // Orchestration metadata (worker IDs, allocation status, page IDs, repo
 // SHAs, etc.) stays on the envelope alongside `outputs`. The discipline

package/src/workflow/lib/agent-role.ts

@@ -60,7 +60,7 @@ export const AGENT_RUN_ROLES = [
   /**
    * Studio chat-author. Read-only authoring co-pilot bound to the
    * `studio-{workflow|manifest|spec}-author` workspace manifests
-   * shipped by `biomes/kernel/studio-author`. The agent emits typed
+   * shipped by the `studio-author` biome. The agent emits typed
    * proposals only — apply goes through the standard write APIs on
    * user confirmation. Interactive surface; never runs in a pipeline.
    */
@@ -70,8 +70,8 @@ export const AGENT_RUN_ROLES = [
    * project's attached repo. Planner-only `webapp-coordinator` agent
    * orchestrates scaffolder + page-builder + data-builder sub-agents.
    * Interactive surface; never runs in a pipeline. Bound to the
-   * `webapp-studio-default` workspace manifest shipped by
-   * `biomes/platform/webapp-studio`.
+   * `webapp-studio-default` workspace manifest shipped by the
+   * `webapp-studio` biome.
    */
   'webapp-studio',
   /**
@@ -81,8 +81,8 @@ export const AGENT_RUN_ROLES = [
    * workspace-proxy's document-sync component derives the reviewable
    * diff and persists it to knowledge-base-api. Interactive surface;
    * never runs in a pipeline. Bound to the `document-md-default` /
-   * `document-rich-default` workspace manifests shipped by
-   * `biomes/platform/document-buddy`.
+   * `document-rich-default` workspace manifests shipped by the
+   * `document-buddy` biome.
    */
   'document',
 ] as const;

package/src/workflow/lib/artifact-ref.ts

@@ -74,7 +74,7 @@ export function isArtifactRef(value: unknown): value is ArtifactRef {
  * Closed set of `ArtifactRef` member names — i.e. the fields a DSL
  * expression `outputs.<name>.<field>` can read directly off the
  * envelope without fetching artifact bytes. Anything else is treated
- * as a payload-reach-in by the DSL compiler (§C.1).
+ * as a payload-reach-in by the DSL compiler.
  *
  * Kept here so the DSL compiler, the worker evaluator, and any future
  * static-analysis tools share one source of truth.

package/src/workflow/lib/compiled-run.ts

@@ -297,7 +297,7 @@ export interface CompiledJob extends BiomeAvailabilityScoped {
  * The compiler emits at most one pin per `(consumerJob, upstreamJob)`
  * pair because the deliverable-spec binding on an upstream activity is
  * job-level today (`with.deliverableSpecRef`). When per-output spec
- * bindings land (plan §B), this shape extends with `outputName` and the
+ * bindings land, this shape extends with `outputName` and the
  * cardinality changes to `(consumerJob, upstreamJob, outputName)`.
  */
 export interface PayloadReachInPin {
@@ -342,7 +342,7 @@ export interface CompiledStaticMatrixStrategy {
  * Matrix expanded at runtime. `fromExpression` is the expression the root
  * workflow evaluates once upstream outputs are available; it must resolve
  * to an array of bindings. `maxParallel` caps concurrent child spawns.
- * The compile-time cardinality cap (plan §5) is enforced at runtime by
+ * The compile-time cardinality cap is enforced at runtime by
  * rejecting arrays > maxEntries.
  */
 export interface CompiledDynamicMatrixStrategy {

package/src/workflow/lib/compiled-workspace-manifest.ts

@@ -77,7 +77,7 @@ export interface CompiledManifestAgent {
   readonly defaultModel?: ModelRef;
   /**
    * Optional node-level instructions carried through from the authored
-   * manifest's `spec.agent.instructions` (WS5 Phase B: author a migrated
+   * manifest's `spec.agent.instructions` (authoring a migrated
    * agent as `base agent slug + instructions`). A prompt fragment the
    * runtime layers ONTO the referenced base agent's intrinsic system
    * prompt — semantically the same as `AgentNode.instructions`.
@@ -94,7 +94,7 @@ export interface CompiledManifestAgent {
   readonly promptMode?: PromptMergeMode;
   /**
    * Optional node-level permission override carried through from the
-   * authored manifest's `spec.agent.permission` (WS5 kernel extension).
+   * authored manifest's `spec.agent.permission` (kernel extension).
    * Deep-merged (per top-level key) over the referenced base agent's
    * authored permission before the system tiers run — lets a generic base
    * agent (e.g. `coder`/`planner`) be specialized into a bounded role