@openwop/openwop-conformance 1.162.0 → 2.0.0-rc.0

package/src/scenarios/envelope-truncated.test.ts

@@ -20,6 +20,8 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { req } from '../lib/requirement-ids.js';
+import { softSkip } from '../lib/soft-skip.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
 const FIXTURE = 'conformance-envelope-truncated';
@@ -56,20 +58,20 @@ async function lastBudget(): Promise<number | null> {
 
 describe.skipIf(HTTP_SKIP)('envelope-truncated: runtime behavior (RFC 0032 §B.4 + RFC 0033 §B)', () => {
   it('when mock returns stopReason: max_tokens on attempt 1, exactly one envelope.truncated event fires with stopReason: max_tokens', async () => {
-    if (!isFixtureAdvertised(FIXTURE)) return;
+    if (!isFixtureAdvertised(FIXTURE)) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `!isFixtureAdvertised(FIXTURE)` returned early');
     const seed = await programMock([
       { stopReason: 'max_tokens', content: '{"valid":' },
       { stopReason: 'end_turn', content: '{"valid":true}' },
     ]);
-    if (seed.status === 404) return;
+    if (seed.status === 404) return softSkip('blocked', 'precondition not met — `seed.status === 404` returned early (seam, prior step, or fixture unavailable)');
     expect(seed.status).toBe(200);
 
     const result = await startRunAndRead();
-    if (result === null) return;
+    if (result === null) return softSkip('blocked', 'precondition not met — `result === null` returned early (seam, prior step, or fixture unavailable)');
     const truncated = result.events.filter((e) => e.type === 'envelope.truncated');
     expect(
       truncated.length,
-      driver.describe(
+      req('openwop.it.envelope-truncated.when-mock-returns-stopreason-max-tokens-on-attempt-1-exactly-one-envelope-trunca', 
         'RFCS/0032-envelope-reliability-events.md §B.4',
         'exactly one envelope.truncated event MUST fire when the provider returns finishReason corresponding to truncation',
       ),
@@ -78,17 +80,17 @@ describe.skipIf(HTTP_SKIP)('envelope-truncated: runtime behavior (RFC 0032 §B.4
   });
 
   it('payload includes nodeId + provider + model + partialPayloadAvailable boolean', async () => {
-    if (!isFixtureAdvertised(FIXTURE)) return;
+    if (!isFixtureAdvertised(FIXTURE)) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `!isFixtureAdvertised(FIXTURE)` returned early');
     const seed = await programMock([
       { stopReason: 'max_tokens', content: '{"partial' },
       { stopReason: 'end_turn', content: '{"valid":true}' },
     ]);
-    if (seed.status === 404) return;
+    if (seed.status === 404) return softSkip('blocked', 'precondition not met — `seed.status === 404` returned early (seam, prior step, or fixture unavailable)');
 
     const result = await startRunAndRead();
-    if (result === null) return;
+    if (result === null) return softSkip('blocked', 'precondition not met — `result === null` returned early (seam, prior step, or fixture unavailable)');
     const truncated = result.events.find((e) => e.type === 'envelope.truncated');
-    expect(truncated).toBeDefined();
+    expect(truncated, req('openwop.it.envelope-truncated.payload-includes-nodeid-provider-model-partialpayloadavailable-boolean', 'RFC 0032 §B.4', 'payload includes nodeId + provider + model + partialPayloadAvailable boolean')).toBeDefined();
     const payload = truncated!.payload ?? {};
     expect(payload.nodeId).toBe(NODE_ID);
     expect(payload.provider).toBe('mock');
@@ -97,24 +99,24 @@ describe.skipIf(HTTP_SKIP)('envelope-truncated: runtime behavior (RFC 0032 §B.4
   });
 
   it('retry attempt receives a maxTokens value strictly greater than the previous attempt (RFC 0033 §B truncationBudgetMultiplier)', async () => {
-    if (!isFixtureAdvertised(FIXTURE)) return;
+    if (!isFixtureAdvertised(FIXTURE)) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `!isFixtureAdvertised(FIXTURE)` returned early');
     const seed = await programMock([
       { stopReason: 'max_tokens', content: '{"partial' },
       { stopReason: 'end_turn', content: '{"valid":true}' },
     ]);
-    if (seed.status === 404) return;
+    if (seed.status === 404) return softSkip('blocked', 'precondition not met — `seed.status === 404` returned early (seam, prior step, or fixture unavailable)');
 
     const result = await startRunAndRead();
-    if (result === null) return;
+    if (result === null) return softSkip('blocked', 'precondition not met — `result === null` returned early (seam, prior step, or fixture unavailable)');
     // After the run, the mock's most-recent budget is the SECOND (retry)
     // attempt's maxTokens. Per RFC 0033 §B, this MUST exceed the fixture's
     // initial maxTokens (50). The host's default multiplier is 2 — so the
     // retry should see 100.
     const budget = await lastBudget();
-    if (budget === null) return; // host doesn't expose the seam
+    if (budget === null) return softSkip('blocked', 'precondition not met — `budget === null` returned early (host doesn\'t expose the seam) (seam, prior step, or fixture unavailable)'); // host doesn't expose the seam
     expect(
       budget,
-      driver.describe(
+      req('openwop.it.envelope-truncated.retry-attempt-receives-a-maxtokens-value-strictly-greater-than-the-previous-atte', 
         'RFCS/0033-envelope-completion-contract.md §B',
         'truncation retry MUST issue with a strictly-increased maxTokens budget (host multiplies by capabilities.envelopes.reliability.completion.truncationBudgetMultiplier)',
       ),
@@ -122,15 +124,15 @@ describe.skipIf(HTTP_SKIP)('envelope-truncated: runtime behavior (RFC 0032 §B.4
   });
 
   it('run terminates `completed` after the second attempt succeeds', async () => {
-    if (!isFixtureAdvertised(FIXTURE)) return;
+    if (!isFixtureAdvertised(FIXTURE)) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `!isFixtureAdvertised(FIXTURE)` returned early');
     const seed = await programMock([
       { stopReason: 'max_tokens', content: '{"partial' },
       { stopReason: 'end_turn', content: '{"valid":true}' },
     ]);
-    if (seed.status === 404) return;
+    if (seed.status === 404) return softSkip('blocked', 'precondition not met — `seed.status === 404` returned early (seam, prior step, or fixture unavailable)');
 
     const result = await startRunAndRead();
-    if (result === null) return;
-    expect((result.terminal as { status?: string }).status).toBe('completed');
+    if (result === null) return softSkip('blocked', 'precondition not met — `result === null` returned early (seam, prior step, or fixture unavailable)');
+    expect((result.terminal as { status?: string }).status, req('openwop.it.envelope-truncated.run-terminates-completed-after-the-second-attempt-succeeds', 'RFC 0032 §B.4', 'run terminates `completed` after the second attempt succeeds')).toBe('completed');
   });
 });

package/src/scenarios/envelope-truncation-cap-exhaustion.test.ts

@@ -19,6 +19,8 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { req } from '../lib/requirement-ids.js';
+import { softSkip } from '../lib/soft-skip.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
 const FIXTURE = 'conformance-envelope-truncation-cap-exhaustion';
@@ -57,24 +59,24 @@ const PERPETUAL_TRUNCATION = Array.from({ length: 16 }, () => ({
 
 describe.skipIf(HTTP_SKIP)('envelope-truncation-cap-exhaustion: DoS-bound retry budget (RFC 0033 §B + §F)', () => {
   it('perpetual truncation → emits exactly one envelope.retry.exhausted with finalReason: "truncation"', async () => {
-    if (!isFixtureAdvertised(FIXTURE)) return;
+    if (!isFixtureAdvertised(FIXTURE)) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `!isFixtureAdvertised(FIXTURE)` returned early');
     const seed = await programMock(PERPETUAL_TRUNCATION);
-    if (seed.status === 404) return;
+    if (seed.status === 404) return softSkip('blocked', 'precondition not met — `seed.status === 404` returned early (seam, prior step, or fixture unavailable)');
     expect(seed.status).toBe(200);
 
     const result = await startRunAndRead();
-    if (result === null) return;
+    if (result === null) return softSkip('blocked', 'precondition not met — `result === null` returned early (seam, prior step, or fixture unavailable)');
     const exhausted = result.events.filter((e) => e.type === 'envelope.retry.exhausted');
     expect(
       exhausted.length,
-      driver.describe(
+      req('openwop.it.envelope-truncation-cap-exhaustion.perpetual-truncation-emits-exactly-one-envelope-retry-exhausted-with-finalreason', 
         'RFCS/0032-envelope-reliability-events.md §B.2',
         'exactly one envelope.retry.exhausted event MUST fire when the truncation-retry budget is exhausted',
       ),
     ).toBe(1);
     expect(
       exhausted[0]!.payload?.finalReason,
-      driver.describe(
+      req('openwop.it.envelope-truncation-cap-exhaustion.perpetual-truncation-emits-exactly-one-envelope-retry-exhausted-with-finalreason', 
         'RFCS/0033-envelope-completion-contract.md §B',
         'finalReason MUST be "truncation" when the host exhausts truncation retries (distinguished from schema-violation per RFC 0033 §A)',
       ),
@@ -82,16 +84,16 @@ describe.skipIf(HTTP_SKIP)('envelope-truncation-cap-exhaustion: DoS-bound retry
   });
 
   it('node fails with RunSnapshot.error.code: "envelope_truncation_unrecoverable" per RFC 0033 §F', async () => {
-    if (!isFixtureAdvertised(FIXTURE)) return;
+    if (!isFixtureAdvertised(FIXTURE)) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `!isFixtureAdvertised(FIXTURE)` returned early');
     const seed = await programMock(PERPETUAL_TRUNCATION);
-    if (seed.status === 404) return;
+    if (seed.status === 404) return softSkip('blocked', 'precondition not met — `seed.status === 404` returned early (seam, prior step, or fixture unavailable)');
 
     const result = await startRunAndRead();
-    if (result === null) return;
+    if (result === null) return softSkip('blocked', 'precondition not met — `result === null` returned early (seam, prior step, or fixture unavailable)');
     const code = (result.terminal as { error?: { code?: string } }).error?.code;
     expect(
       code,
-      driver.describe(
+      req('openwop.it.envelope-truncation-cap-exhaustion.node-fails-with-runsnapshot-error-code-envelope-truncation-unrecoverable-per-rfc', 
         'RFCS/0033-envelope-completion-contract.md §F',
         'truncation-retry-exhaustion MUST surface as RunSnapshot.error.code = envelope_truncation_unrecoverable (distinct from envelope_invalid which surfaces schema-violation-exhaustion)',
       ),
@@ -99,18 +101,18 @@ describe.skipIf(HTTP_SKIP)('envelope-truncation-cap-exhaustion: DoS-bound retry
   });
 
   it('total LLM calls bounded by maxRetryAttempts (DoS-bound — no infinite loop)', async () => {
-    if (!isFixtureAdvertised(FIXTURE)) return;
+    if (!isFixtureAdvertised(FIXTURE)) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `!isFixtureAdvertised(FIXTURE)` returned early');
     const seed = await programMock(PERPETUAL_TRUNCATION);
-    if (seed.status === 404) return;
+    if (seed.status === 404) return softSkip('blocked', 'precondition not met — `seed.status === 404` returned early (seam, prior step, or fixture unavailable)');
 
     const result = await startRunAndRead();
-    if (result === null) return;
+    if (result === null) return softSkip('blocked', 'precondition not met — `result === null` returned early (seam, prior step, or fixture unavailable)');
     // Count envelope.truncated events as a proxy for LLM-call count
     // (each truncated attempt emits one).
     const truncatedCount = result.events.filter((e) => e.type === 'envelope.truncated').length;
     expect(
       truncatedCount,
-      driver.describe(
+      req('openwop.it.envelope-truncation-cap-exhaustion.total-llm-calls-bounded-by-maxretryattempts-dos-bound-no-infinite-loop', 
         'RFCS/0033-envelope-completion-contract.md §B',
         'truncation-retry count MUST be bounded — host cannot loop indefinitely doubling budget; expected upper-bound matches advertised maxRetryAttempts',
       ),
@@ -123,19 +125,19 @@ describe.skipIf(HTTP_SKIP)('envelope-truncation-cap-exhaustion: DoS-bound retry
   });
 
   it('envelope.retry.exhausted is emitted BEFORE node.failed (cause precedes effect)', async () => {
-    if (!isFixtureAdvertised(FIXTURE)) return;
+    if (!isFixtureAdvertised(FIXTURE)) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `!isFixtureAdvertised(FIXTURE)` returned early');
     const seed = await programMock(PERPETUAL_TRUNCATION);
-    if (seed.status === 404) return;
+    if (seed.status === 404) return softSkip('blocked', 'precondition not met — `seed.status === 404` returned early (seam, prior step, or fixture unavailable)');
 
     const result = await startRunAndRead();
-    if (result === null) return;
+    if (result === null) return softSkip('blocked', 'precondition not met — `result === null` returned early (seam, prior step, or fixture unavailable)');
     const exhaustedIdx = result.events.findIndex((e) => e.type === 'envelope.retry.exhausted');
     const failedIdx = result.events.findIndex((e) => e.type === 'node.failed');
     expect(exhaustedIdx).toBeGreaterThanOrEqual(0);
     expect(failedIdx).toBeGreaterThanOrEqual(0);
     expect(
       exhaustedIdx < failedIdx,
-      driver.describe(
+      req('openwop.it.envelope-truncation-cap-exhaustion.envelope-retry-exhausted-is-emitted-before-node-failed-cause-precedes-effect', 
         'RFCS/0032-envelope-reliability-events.md §B.2',
         'envelope.retry.exhausted MUST be emitted BEFORE node.failed',
       ),

package/src/scenarios/envelope-variant-discriminator-static.test.ts

@@ -21,6 +21,7 @@ import { describe, it, expect } from 'vitest';
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { SCHEMAS_DIR } from '../lib/paths.js';
+import { req } from '../lib/requirement-ids.js';
 
 interface DiscriminatorViolation {
   path: string;
@@ -124,7 +125,7 @@ describe('envelope-variant-discriminator-static (RFC 0031 §A)', () => {
   it('local envelope-schema directory is discoverable', () => {
     expect(
       schemas.length,
-      'schemas/envelopes/*.schema.json MUST contain at least the four universal-kind schemas',
+      req('openwop.it.envelope-variant-discriminator-static.local-envelope-schema-directory-is-discoverable', 'RFC 0031 §A', 'schemas/envelopes/*.schema.json MUST contain at least the four universal-kind schemas'),
     ).toBeGreaterThanOrEqual(4);
   });
 
@@ -135,7 +136,7 @@ describe('envelope-variant-discriminator-static (RFC 0031 §A)', () => {
       walkForOneOf(schema, '#', violations);
       expect(
         violations,
-        `${kind}.schema.json contains \`oneOf\` — REFORMULATE as \`anyOf\` + single-string-enum discriminator per RFC 0031 §A. Violations: ${JSON.stringify(violations, null, 2)}`,
+        req('openwop.it.envelope-variant-discriminator-static.schema-json-must-not-contain-oneof-at-any-nesting-depth-gemini-silently-drops-it', 'RFC 0031 §A', `${kind}.schema.json contains \`oneOf\` — REFORMULATE as \`anyOf\` + single-string-enum discriminator per RFC 0031 §A. Violations: ${JSON.stringify(violations, null, 2)}`),
       ).toEqual([]);
     });
 
@@ -145,7 +146,7 @@ describe('envelope-variant-discriminator-static (RFC 0031 §A)', () => {
       walkForAnyOfDiscriminators(schema, '#', violations);
       expect(
         violations,
-        `${kind}.schema.json \`anyOf\` discriminator violations: ${JSON.stringify(violations, null, 2)}`,
+        req('openwop.it.envelope-variant-discriminator-static.schema-json-every-anyof-branch-declares-a-single-string-enum-discriminator-in-re', 'RFC 0031 §A', `${kind}.schema.json \`anyOf\` discriminator violations: ${JSON.stringify(violations, null, 2)}`),
       ).toEqual([]);
     });
   }

package/src/scenarios/errors.test.ts

@@ -8,6 +8,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { req } from '../lib/requirement-ids.js';
 
 interface ErrorEnvelope {
   error: unknown;
@@ -16,28 +17,28 @@ interface ErrorEnvelope {
   [key: string]: unknown;
 }
 
-function assertErrorEnvelope(body: unknown, specSection: string): void {
-  expect(typeof body, driver.describe(specSection, 'error response MUST be a JSON object')).toBe(
+function assertErrorEnvelope(requirementId: string, body: unknown, specSection: string): void {
+  expect(typeof body, req(requirementId, specSection, 'error response MUST be a JSON object')).toBe(
     'object',
   );
   const env = body as ErrorEnvelope;
 
-  expect(typeof env.error, driver.describe(
+  expect(typeof env.error, req(requirementId, 
     specSection,
     'error envelope MUST include `error` (machine-readable string)',
   )).toBe('string');
 
-  expect(typeof env.message, driver.describe(
+  expect(typeof env.message, req(requirementId, 
     specSection,
     'error envelope MUST include `message` (human-readable string)',
   )).toBe('string');
 
   if (env.details !== undefined) {
-    expect(typeof env.details, driver.describe(
+    expect(typeof env.details, req(requirementId, 
       specSection,
       'error envelope `details` (when present) MUST be a JSON object',
     )).toBe('object');
-    expect(env.details, driver.describe(
+    expect(env.details, req(requirementId, 
       specSection,
       'error envelope `details` (when present) MUST NOT be null',
     )).not.toBeNull();
@@ -51,7 +52,7 @@ function assertErrorEnvelope(body: unknown, specSection: string): void {
   const extraneousKeys = Object.keys(env as Record<string, unknown>).filter(
     (k) => !allowedKeys.has(k),
   );
-  expect(extraneousKeys, driver.describe(
+  expect(extraneousKeys, req(requirementId, 
     'schemas/error-envelope.schema.json (additionalProperties:false)',
     `error envelope MUST NOT have keys outside {error, message, details}; extraneous: [${extraneousKeys.join(', ')}]`,
   )).toEqual([]);
@@ -64,7 +65,7 @@ function assertErrorEnvelope(body: unknown, specSection: string): void {
  * RECOMMENDED, not REQUIRED — hosts that don't emit trace IDs are still
  * conformant. This helper just pins the placement.
  */
-function assertCorrelationIdShape(body: unknown, specSection: string): void {
+function assertCorrelationIdShape(requirementId: string, body: unknown, specSection: string): void {
   const env = body as ErrorEnvelope;
   // Top-level correlationId would be a spec violation; the assertErrorEnvelope
   // additionalProperties check above catches it. This helper additionally
@@ -72,11 +73,11 @@ function assertCorrelationIdShape(body: unknown, specSection: string): void {
   if (env.details && typeof env.details === 'object') {
     const det = env.details as Record<string, unknown>;
     if (det.correlationId !== undefined) {
-      expect(typeof det.correlationId, driver.describe(
+      expect(typeof det.correlationId, req(requirementId, 
         specSection,
         'when present, details.correlationId MUST be a string',
       )).toBe('string');
-      expect((det.correlationId as string).length, driver.describe(
+      expect((det.correlationId as string).length, req(requirementId, 
         specSection,
         'details.correlationId MUST be a non-empty string',
       )).toBeGreaterThan(0);
@@ -90,11 +91,11 @@ describe('errors: 404 envelope', () => {
 
     expect(
       [403, 404].includes(res.status),
-      driver.describe('rest-endpoints.md', 'unknown run MUST return 404 (or 403 if leaking existence is forbidden)'),
+      req('openwop.it.errors.get-v1-runs-nonexistentid-returns-canonical-envelope', 'rest-endpoints.md', 'unknown run MUST return 404 (or 403 if leaking existence is forbidden)'),
     ).toBe(true);
 
-    assertErrorEnvelope(res.json, 'rest-endpoints.md error envelope');
-    assertCorrelationIdShape(res.json, 'rest-endpoints.md §error-envelope');
+    assertErrorEnvelope('openwop.it.errors.get-v1-runs-nonexistentid-returns-canonical-envelope', res.json, 'rest-endpoints.md error envelope');
+    assertCorrelationIdShape('openwop.it.errors.get-v1-runs-nonexistentid-returns-canonical-envelope', res.json, 'rest-endpoints.md §error-envelope');
   });
 });
 
@@ -107,12 +108,12 @@ describe('errors: 400 envelope (validation)', () => {
     // not the status code.
     expect(
       res.status,
-      driver.describe('rest-endpoints.md', 'malformed POST /v1/runs MUST return 4xx'),
+      req('openwop.it.errors.post-v1-runs-with-empty-body-returns-canonical-envelope', 'rest-endpoints.md', 'malformed POST /v1/runs MUST return 4xx'),
     ).toBeGreaterThanOrEqual(400);
     expect(res.status).toBeLessThan(500);
 
-    assertErrorEnvelope(res.json, 'rest-endpoints.md error envelope');
-    assertCorrelationIdShape(res.json, 'rest-endpoints.md §error-envelope');
+    assertErrorEnvelope('openwop.it.errors.post-v1-runs-with-empty-body-returns-canonical-envelope', res.json, 'rest-endpoints.md error envelope');
+    assertCorrelationIdShape('openwop.it.errors.post-v1-runs-with-empty-body-returns-canonical-envelope', res.json, 'rest-endpoints.md §error-envelope');
   });
 });
 
@@ -131,12 +132,12 @@ describe('errors: details.correlationId placement convention', () => {
     const res = await driver.get('/v1/runs/openwop-conformance-correlation-probe-' + Date.now());
     expect(
       [400, 403, 404].includes(res.status),
-      driver.describe('rest-endpoints.md', 'unknown run returns 4xx envelope'),
+      req('openwop.it.errors.correlationid-when-emitted-on-5xx-must-be-in-details-never-top-level', 'rest-endpoints.md', 'unknown run returns 4xx envelope'),
     ).toBe(true);
     const body = res.json as Record<string, unknown>;
-    expect(body, driver.describe('rest-endpoints.md', 'response MUST be a JSON object')).toBeDefined();
+    expect(body, req('openwop.it.errors.correlationid-when-emitted-on-5xx-must-be-in-details-never-top-level', 'rest-endpoints.md', 'response MUST be a JSON object')).toBeDefined();
     // The structural constraint: no top-level correlationId.
-    expect(body.correlationId, driver.describe(
+    expect(body.correlationId, req('openwop.it.errors.correlationid-when-emitted-on-5xx-must-be-in-details-never-top-level', 
       'spec/v1/rest-endpoints.md §error-envelope (correlationId convention)',
       'correlationId MUST NOT appear at the top level of the error envelope; canonical home is `details.correlationId`',
     )).toBeUndefined();

package/src/scenarios/eventOrdering.test.ts

@@ -19,6 +19,8 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { req } from '../lib/requirement-ids.js';
+import { softSkip } from '../lib/soft-skip.js';
 
 const NOOP_WORKFLOW_ID = 'conformance-noop';
 const SKIP_NO_NOOP = !isFixtureAdvertised(NOOP_WORKFLOW_ID);
@@ -48,18 +50,18 @@ describe.skipIf(SKIP_NO_NOOP)('event-ordering: polling returns events in monoton
     await pollUntilTerminal(runId);
 
     const res = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events/poll`);
-    if (res.status !== 200) return;
+    if (res.status !== 200) return softSkip('blocked', 'precondition not met — `res.status !== 200` returned early (seam, prior step, or fixture unavailable)');
 
     const body = res.json as { events?: RawEvent[] } | undefined;
-    if (!body?.events) return;
-    if (body.events.length < 2) return; // single-event runs have no ordering to verify
+    if (!body?.events) return softSkip('blocked', 'precondition not met — `!body?.events` returned early (seam, prior step, or fixture unavailable)');
+    if (body.events.length < 2) return softSkip('blocked', 'precondition not met — `body.events.length < 2` returned early (single-event runs have no ordering to verify) (seam, prior step, or fixture unavailable)'); // single-event runs have no ordering to verify
 
     const seqs = body.events.map(getSeq);
     for (let i = 1; i < seqs.length; i++) {
       const curr = seqs[i];
       const prev = seqs[i - 1];
       if (curr === null || prev === null) continue; // host without seq fields
-      expect(curr, driver.describe(
+      expect(curr, req('openwop.it.eventOrdering.events-from-a-single-poll-have-non-decreasing-sequence-numbers', 
         'observability.md §"Event ordering"',
         `event[${i}].sequence (${curr}) MUST be >= event[${i - 1}].sequence (${prev})`,
       )).toBeGreaterThanOrEqual(prev);
@@ -74,13 +76,13 @@ describe.skipIf(SKIP_NO_NOOP)('event-ordering: polling returns events in monoton
 
     const a = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events/poll`);
     const b = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events/poll`);
-    if (a.status !== 200 || b.status !== 200) return;
+    if (a.status !== 200 || b.status !== 200) return softSkip('blocked', 'precondition not met — `a.status !== 200 || b.status !== 200` returned early (seam, prior step, or fixture unavailable)');
 
     const aBody = a.json as { events?: RawEvent[] } | undefined;
     const bBody = b.json as { events?: RawEvent[] } | undefined;
-    if (!aBody?.events || !bBody?.events) return;
+    if (!aBody?.events || !bBody?.events) return softSkip('blocked', 'precondition not met — `!aBody?.events || !bBody?.events` returned early (seam, prior step, or fixture unavailable)');
 
-    expect(aBody.events.length, driver.describe(
+    expect(aBody.events.length, req('openwop.it.eventOrdering.repeated-polls-of-a-terminal-run-yield-identical-event-sequences', 
       'observability.md',
       'repeated polls of terminal run MUST return same number of events',
     )).toBe(bBody.events.length);
@@ -89,7 +91,7 @@ describe.skipIf(SKIP_NO_NOOP)('event-ordering: polling returns events in monoton
       const aSeq = getSeq(aBody.events[i]!);
       const bSeq = getSeq(bBody.events[i]!);
       if (aSeq === null || bSeq === null) continue;
-      expect(aSeq, driver.describe(
+      expect(aSeq, req('openwop.it.eventOrdering.repeated-polls-of-a-terminal-run-yield-identical-event-sequences', 
         'observability.md',
         `event[${i}] sequence MUST be stable across repeated polls`,
       )).toBe(bSeq);
@@ -105,15 +107,15 @@ describe.skipIf(SKIP_NO_NOOP)('event-ordering: terminal run has at most one term
     await pollUntilTerminal(runId);
 
     const res = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events/poll`);
-    if (res.status !== 200) return;
+    if (res.status !== 200) return softSkip('blocked', 'precondition not met — `res.status !== 200` returned early (seam, prior step, or fixture unavailable)');
 
     const body = res.json as { events?: RawEvent[] } | undefined;
-    if (!body?.events) return;
+    if (!body?.events) return softSkip('blocked', 'precondition not met — `!body?.events` returned early (seam, prior step, or fixture unavailable)');
 
     const TERMINAL_TYPES = new Set(['run.completed', 'run.failed', 'run.cancelled']);
     const terminalCount = body.events.filter((e) => typeof e.type === 'string' && TERMINAL_TYPES.has(e.type)).length;
 
-    expect(terminalCount, driver.describe(
+    expect(terminalCount, req('openwop.it.eventOrdering.event-stream-contains-exactly-one-of-run-completed-run-failed-run-cancelled', 
       'observability.md §"Run lifecycle events"',
       'a run MUST emit exactly one terminal event (run.completed / run.failed / run.cancelled)',
     )).toBe(1);
@@ -126,16 +128,16 @@ describe.skipIf(SKIP_NO_NOOP)('event-ordering: terminal run has at most one term
     await pollUntilTerminal(runId);
 
     const res = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events/poll`);
-    if (res.status !== 200) return;
+    if (res.status !== 200) return softSkip('blocked', 'precondition not met — `res.status !== 200` returned early (seam, prior step, or fixture unavailable)');
 
     const body = res.json as { events?: RawEvent[] } | undefined;
-    if (!body?.events || body.events.length === 0) return;
+    if (!body?.events || body.events.length === 0) return softSkip('blocked', 'precondition not met — `!body?.events || body.events.length === 0` returned early (seam, prior step, or fixture unavailable)');
 
     const TERMINAL_TYPES = new Set(['run.completed', 'run.failed', 'run.cancelled']);
     const lastEvent = body.events[body.events.length - 1]!;
     expect(
       typeof lastEvent.type === 'string' && TERMINAL_TYPES.has(lastEvent.type),
-      driver.describe(
+      req('openwop.it.eventOrdering.the-terminal-event-is-the-last-event-in-the-stream', 
         'observability.md §"Run lifecycle events"',
         'terminal event MUST be the last event in the stream — no events after a terminal type',
       ),

package/src/scenarios/exec-not-protocol-tier.test.ts

@@ -26,9 +26,7 @@ import { describe, it, expect } from 'vitest';
 import { readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { SCHEMAS_DIR } from '../lib/paths.js';
-
-/** Server-free assertion-message helper (mirrors driver.describe's "spec — requirement" shape without requiring OPENWOP_BASE_URL). */
-const why = (specRef: string, requirement: string): string => `${specRef} — ${requirement}`;
+import { req } from '../lib/requirement-ids.js';
 
 /**
  * Closed denylist of exec-class identifier *segments* (whole tokens). The
@@ -79,7 +77,7 @@ describe('exec-not-protocol-tier: no exec-class primitive in the protocol corpus
     }
     expect(
       offenders,
-      why(
+      req('openwop.it.exec-not-protocol-tier.no-protocol-owned-core-openwop-identifier-denotes-arbitrary-command-execution', 
         'host-extensions.md §exec-class tools',
         'the protocol corpus MUST NOT define a core.*/openwop.* exec-class identifier',
       ),
@@ -105,7 +103,7 @@ describe('exec-not-protocol-tier: no exec-class primitive in the protocol corpus
     walkProps(caps, 'capabilities');
     expect(
       offenders,
-      why('host-extensions.md §exec-class tools', 'capabilities.schema.json MUST NOT declare an exec-class capability flag'),
+      req('openwop.it.exec-not-protocol-tier.no-capabilities-schema-json-property-name-denotes-arbitrary-command-execution', 'host-extensions.md §exec-class tools', 'capabilities.schema.json MUST NOT declare an exec-class capability flag'),
     ).toEqual([]);
   });
 
@@ -120,12 +118,12 @@ describe('exec-not-protocol-tier: no exec-class primitive in the protocol corpus
     });
     expect(
       offenders,
-      why('host-extensions.md §exec-class tools', 'no RunEventType MUST denote arbitrary command execution'),
+      req('openwop.it.exec-not-protocol-tier.the-canonical-runeventtype-vocabulary-contains-no-exec-class-event', 'host-extensions.md §exec-class tools', 'no RunEventType MUST denote arbitrary command execution'),
     ).toEqual([]);
   });
 
   it('positive control: a vendor / x-host exec identifier is allowed (host-extension namespace)', () => {
-    expect(isExecClass('vendor.acme.exec')).toBe(false);
+    expect(isExecClass('vendor.acme.exec'), req('openwop.it.exec-not-protocol-tier.positive-control-a-vendor-x-host-exec-identifier-is-allowed-host-extension-names', 'RFC 0069', 'positive control: a vendor / x-host exec identifier is allowed (host-extension namespace)')).toBe(false);
     expect(isExecClass('x-host-acme-exec')).toBe(false);
     expect(isExecClass('private.host.shell')).toBe(false);
     // And the denylist actually fires on a protocol-owned id:

package/src/scenarios/experimental-tier-shape.test.ts

@@ -31,6 +31,8 @@ import { driver } from '../lib/driver.js';
 import { experimentalGate } from '../lib/behavior-gate.js';
 import { __resetEnvCacheForTests } from '../lib/env.js';
 import { capabilityFamily } from '../lib/discovery-capabilities.js';
+import { req } from '../lib/requirement-ids.js';
+import { softSkip } from '../lib/soft-skip.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
 
@@ -62,15 +64,15 @@ describe.skipIf(HTTP_SKIP)('experimental-tier-shape: §A schema discipline (RFC
     const em = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel;
     if (em === undefined) {
       ctx.skip();
-      return;
+      return softSkip('blocked', 'precondition not met — `em === undefined` returned early (seam, prior step, or fixture unavailable)');
     }
     if (em.tier === undefined) {
       ctx.skip(); // tier is optional with default 'stable'
-      return;
+      return softSkip('blocked', 'precondition not met — `em.tier === undefined` returned early (seam, prior step, or fixture unavailable)');
     }
     expect(
       em.tier === 'stable' || em.tier === 'experimental',
-      driver.describe(
+      req('openwop.it.experimental-tier-shape.multiagent-executionmodel-tier-when-present-must-be-one-of-stable-experimental', 
         'RFCS/0042-experimental-capability-tier.md §A',
         'multiAgent.executionModel.tier MUST be one of the canonical enum values',
       ),
@@ -82,12 +84,12 @@ describe.skipIf(HTTP_SKIP)('experimental-tier-shape: §A schema discipline (RFC
     const em = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel;
     if (em === undefined || em.tier !== 'experimental') {
       ctx.skip();
-      return;
+      return softSkip('blocked', 'precondition not met — `em === undefined || em.tier !== \'experimental\'` returned early (seam, prior step, or fixture unavailable)');
     }
 
     expect(
       typeof em.experimentalUntil,
-      driver.describe(
+      req('openwop.it.experimental-tier-shape.when-tier-experimental-experimentaluntil-must-be-present-valid-date', 
         'RFCS/0042-experimental-capability-tier.md §B',
         'when tier is "experimental", experimentalUntil MUST be present (the §B sunset-rule contract)',
       ),
@@ -96,7 +98,7 @@ describe.skipIf(HTTP_SKIP)('experimental-tier-shape: §A schema discipline (RFC
     const dateStr = em.experimentalUntil as string;
     expect(
       /^\d{4}-\d{2}-\d{2}$/.test(dateStr),
-      driver.describe(
+      req('openwop.it.experimental-tier-shape.when-tier-experimental-experimentaluntil-must-be-present-valid-date', 
         'RFCS/0042-experimental-capability-tier.md §B',
         'experimentalUntil MUST match YYYY-MM-DD',
       ),
@@ -105,7 +107,7 @@ describe.skipIf(HTTP_SKIP)('experimental-tier-shape: §A schema discipline (RFC
     const parsed = new Date(dateStr + 'T00:00:00Z');
     expect(
       !Number.isNaN(parsed.getTime()),
-      driver.describe(
+      req('openwop.it.experimental-tier-shape.when-tier-experimental-experimentaluntil-must-be-present-valid-date', 
         'RFCS/0042-experimental-capability-tier.md §B',
         'experimentalUntil MUST parse as a valid ISO-8601 date',
       ),
@@ -117,18 +119,18 @@ describe.skipIf(HTTP_SKIP)('experimental-tier-shape: §A schema discipline (RFC
     const em = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel;
     if (em === undefined || em.tier !== 'experimental') {
       ctx.skip();
-      return;
+      return softSkip('blocked', 'precondition not met — `em === undefined || em.tier !== \'experimental\'` returned early (seam, prior step, or fixture unavailable)');
     }
     if (typeof em.experimentalUntil !== 'string') {
       ctx.skip(); // shape probe above will fail; don't double-fail
-      return;
+      return softSkip('blocked', 'precondition not met — `typeof em.experimentalUntil !== \'string\'` returned early (seam, prior step, or fixture unavailable)');
     }
     const target = new Date((em.experimentalUntil as string) + 'T00:00:00Z').getTime();
     const now = Date.now();
     const daysAhead = (target - now) / (1000 * 60 * 60 * 24);
     expect(
       daysAhead <= 365,
-      driver.describe(
+      req('openwop.it.experimental-tier-shape.experimentaluntil-must-be-365-days-in-the-future-sunset-bound', 
         'RFCS/0042-experimental-capability-tier.md §B',
         `experimentalUntil MUST be ≤ 365 days from now (got ${Math.floor(daysAhead)} days; advertised ${em.experimentalUntil})`,
       ),
@@ -140,17 +142,17 @@ describe.skipIf(HTTP_SKIP)('experimental-tier-shape: §A schema discipline (RFC
     const em = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel;
     if (em === undefined || em.tier !== 'experimental') {
       ctx.skip();
-      return;
+      return softSkip('blocked', 'precondition not met — `em === undefined || em.tier !== \'experimental\'` returned early (seam, prior step, or fixture unavailable)');
     }
     if (typeof em.experimentalUntil !== 'string') {
       ctx.skip();
-      return;
+      return softSkip('blocked', 'precondition not met — `typeof em.experimentalUntil !== \'string\'` returned early (seam, prior step, or fixture unavailable)');
     }
     const target = new Date((em.experimentalUntil as string) + 'T00:00:00Z').getTime();
     const now = Date.now();
     expect(
       target >= now,
-      driver.describe(
+      req('openwop.it.experimental-tier-shape.sunset-detection-experimentaluntil-in-the-past-is-non-conformant', 
         'RFCS/0042-experimental-capability-tier.md §B',
         `experimentalUntil MUST NOT be in the past (advertised ${em.experimentalUntil}; host MUST either flip tier to stable, retract the advertisement, or re-advertise with a future date + open deprecation RFC)`,
       ),
@@ -168,7 +170,7 @@ describe.skipIf(HTTP_SKIP)('experimental-tier-shape: §D experimentalGate helper
       const result = experimentalGate('test-profile', true, 'experimental', '2027-05-22');
       expect(
         result,
-        driver.describe(
+        req('openwop.it.experimental-tier-shape.experimentalgate-returns-false-for-tier-experimental-without-openwop-require-exp', 
           'RFCS/0042-experimental-capability-tier.md §D',
           'default mode + tier="experimental" MUST soft-skip — helper returns false',
         ),
@@ -189,7 +191,7 @@ describe.skipIf(HTTP_SKIP)('experimental-tier-shape: §D experimentalGate helper
     __resetEnvCacheForTests();
     try {
       // Stable + advertised → proceed.
-      expect(experimentalGate('test-stable', true, 'stable')).toBe(true);
+      expect(experimentalGate('test-stable', true, 'stable'), req('openwop.it.experimental-tier-shape.experimentalgate-routes-through-behaviorgate-when-tier-undefined-or-stable', 'RFC 0042 §A', 'experimentalGate routes through behaviorGate when tier === undefined or "stable"')).toBe(true);
       expect(experimentalGate('test-stable-undef', true, undefined)).toBe(true);
       // Stable + NOT advertised, default mode → skip (returns false, no throw).
       expect(experimentalGate('test-not-adv', false, 'stable')).toBe(false);