Document the human-approved clear path in the policy skills

[pareilly]

Ready to merge once the production deploy lands. The product-repo change this
tracks is merged and production is deploying now. Both vendored files are re-paired
against the current product-repo main (not the older revision this PR first
vendored) — bundle 91572745…12ede, artifact 22f5fa77…b068, the bundle's sha
matching the product repo's committed sidecar byte for byte.

What this changes

The marker guidance in the policy skills said a marker's TTL is the only way out of a block. It is not — a person can approve a clear in a browser — and the gap ran in the direction that hurts most: an author following it wrote deny reasons telling people to wait an hour for something they could resolve in under a minute. Clearing appeared nowhere in either policy skill, so this is mostly an addition rather than a correction sweep.

dtwo-gateway-config covered the gateway.session_control block, but from a schema artifact old enough to document client_id as required and to know nothing of redirect_uri — so it told every reader to register an IdP application and paste an id, which is the one thing a gateway on Dtwo authentication should not do. That skill's coverage is generated, so the artifact is re-vendored and the digest regenerated rather than hand-edited.

dtwo-policy-rego

• The worked example's deny reason offers the clear as the fast exit and keeps the TTL as the fallback.
• The deny-reason guidance states that rule, and says to phrase it so the sentence still reads correctly where clearing is not armed — there the request returns a readable "not configured" refusal and the TTL half still holds. It also says to word the clear as a recovery the person authorizes, never as a way around the decision.
• A policy may decide on the session intent but must never return it: no interpolating current_intent(input) or its caller-supplied description into a reason or a transform.
• New Reading the registry section: data.dtwo.intent_registry is OPA base data in every policy bundle, with a worked read that sources a deny message from the registry instead of a pasted string, and a default fallback because an unregistered key would otherwise leave the whole reason undefined.

dtwo-gateway-policy

• New Clearing a marker section, alongside the existing "how a marker gets set" material: an agent can request a clear and cannot complete one; the tools take no arguments, so it cannot choose the target; markers and intent clear separately with different scopes; the approver must be the same identity as the caller; and arming is per gateway, so the refusal has to be handled rather than assumed away.
• That section says why the person is in the loop, not only that they are: a marker is worth exactly as much as the agent's inability to remove it, so the human step is the control rather than a tax on the flow, and what the ceremony produces is evidence that a named person, freshly authenticated, authorized this clear of these values. With the rule that follows for an agent — never offer a clear as a way around a correct block; the person judges whether the state has outlived its purpose, and every request is recorded either way.
• The stale "no clear tool" / "lifts only on TTL expiry" claims are corrected in the design-limits summary, the marker constraints list, and the intent_marker_incompatible recovery note.
• The short-TTL testing guidance stays — it is about iterating quickly — but now reads as a tip rather than the only exit, and approving a clear is offered as a third way to reach a clean negative test.
• Arming guidance matches the config skill: write clearing: {enabled: true} explicitly, since an implicit block arms only while intent capture is on and parks inert otherwise — the one shape that leaves marker policies enforcing with no targeted way out of a marker.
• New The registry as policy data section documenting the data.dtwo.intent_registry shape, flagged as not gated: the document ships to every gateway and always carries markers[], whether or not intent capture is enabled.

dtwo-gateway-config — regenerated, not hand-edited

The digest now carries, from the artifact:

• client_id — required yes → no, with guidance to leave it unset under Dtwo authentication, where the platform provisions the ceremony application per organization and the deploy renders its id.
• redirect_uri — new field, with the derivation it overrides and the root-path constraint.
• clearing.enabled — write true whenever you want clearing, rather than leaving the block's meaning to gateway.intent.enabled.
• Two new cross-field constraints: a non-Dtwo IdP must set client_id (the deploy fails rather than arming a ceremony with no application), and redirect_uri replaces the callback otherwise derived from the first jwt_audience entry.
• Six newly reserved env-var names, SESSION_CONTROL_REDIRECT_URI among them.
• The CGNAT / 100.64.0.0/10 note on gateway.ssrf.allowed_networks, and both new oauth_config fields.

Vendored files and pins

Both vendored files come from one source revision. Refreshing the artifact alone would reintroduce the drift defect closed in #34 — redirect_uri documented but strict-rejected by an older bundle, SESSION_CONTROL_REDIRECT_URI reserved in the artifact but accepted inside gateway.advanced. All three pins move together: artifact sha, bundle sha, and bundle version 2.0.0 → 3.0.0.

That version bump is behavioural rather than structural. It adds two must_validate rejections, both on oauth_config: an unimplemented token_endpoint_auth_method (RFC 7591's none included, since the gateway ignores it and the key used to be stripped silently), and client_secret_basic without a client_secret. No fixture or skill file exercises either key, so no rubric semantics move, and the .d.mts shim is unchanged, so the harness's shape assumptions still hold.

Delta against the previously vendored bundle — wider than the version bumps, which count only what the product repo chose to version. session_control.redirect_uri and a session_control block with no client_id are newly accepted; the old bundle rejected both, so the rubric would have scored the shape this skill recommends as invalid. OAuth scopes is now optional ([] default) — the digest previously told readers it was required, which would have sent a scope to providers that reject one. Six env-var names are newly rejected inside gateway.advanced (CPEX_CONTROL_TELEMETRY_DB_ENABLED, CPEX_CONTROL_TELEMETRY_ENABLED, CSRF_ENABLED, MCPGATEWAY_A2A_ENABLED, SESSION_CONTROL_REDIRECT_URI, SOTW_DELETE_POLICY), as is a singular scope key on an oauth block with no scopes. token_endpoint_auth_method / omit_resource now survive a round-trip instead of being stripped. Probed against both bundles directly; every newly-rejected shape was already rejected before, for a different reason, so no rubric result moves.

scripts/generate-schema-digest.mjs renders the two new oauth_config fields. Its field order is an ordered allowlist, so a field added upstream is dropped rather than appended and the script's own coverage check refuses to write the digest until it is placed deliberately — that guardrail is now commented, because hitting it reads like a generator bug.

Verification

• Both Rego snippets touched pass opa check, and the registry example was evaluated with opa eval against a fixture registry and session state, including the missing-entry case the default fallback exists for.
• generate-schema-digest.mjs --check reports the digest in sync with the artifact.
• The vendored bundle's sha256 matches the product repo's committed sidecar byte for byte.
• skill-harness: pnpm test — 177/177 passing against the new bundle (validator bundle 4.0.0).
• dtwo/.claude-plugin/plugin.json bumped to 1.1.8, since distributed skill content changed.

[pareilly]

Ready for review — but please do not merge on approval.

This vendors a schema-reference.json and validator bundle whose source revision is not yet released to production. Plugin content is customer-visible as soon as it lands on main, so merging early would document a config field and guidance that customers cannot use yet.

Review away — the hold is only on the merge button. I'll follow up here once the source revision is out, and that comment is the green light.

[oschaaf]

Led a panel review on this alongside dtwoai/d2#2036: one reviewer checked every behavioural claim in the two policy skills against the gateway source and the product repo, one checked vendoring/pins/harness/public hygiene, and I re-verified each finding before posting. Approving. Honouring the hold — merge is yours, and the button stays untouched until your green-light comment.

Verified true (customer-facing claims, against the pinned gateway release)

• Registry document: shape, field names, FQID-only keys, transitions_* omitted-when-unrestricted / []-when-locked, always fully shaped even for an empty tenant, shipped unconditionally in the same bundle as the Rego, mounted at data.dtwo.intent_registry. The platform's own intent enforcement reads the same document.
• Clear tools: argument-less, hyphenated wire name (the slugifier maps _→-), forced fresh login (prompt=login + max_age), same-identity check, one-login-one-clear, TTL-filtered enumeration, multi-holder flag with "clearing only this one leaves it active", clear_intent offers only the trusted-writer intent, marker/intent clears are disjoint by construction, all-or-nothing commit with rollback on drift, three audit events at mint/authorize/commit.
• Arming semantics match the validator exactly.
• data.dtwo.lib.intent_match ships unconditionally; current_intent / current_category are real rule names.
• Both Rego snippets pass opa check (incl. --strict, --v0-compatible, --v0-v1) and the deploy-time validator. The registry example evaluates with registry text when the entry exists and with the default when it doesn't; removing the default leaves reason undefined while allow stays false — so the "load-bearing" claim is literally true.
• Vendoring: bundle rebuilt from the d2 PR head → 971e2d7c…ee16, byte-identical to the vendored file; schema artifact byte-identical; .d.mts unchanged; VALIDATOR_BUNDLE_VERSION 3.0.0 in both; digest --check in sync and regen is a no-op; the allowlist coverage gate really does refuse to write when a field is missing; harness 177/177; reserved-key counts 21+11+28=60 with six additions and no removals; plugin.json-only bump is the repo convention. Hygiene grep of the artifact, digest and bundle is clean.

Asks (inline)

1. "Handle the 'not configured' refusal" needs a second branch. The reserved server hosting clear_markers is federated only when intent capture is on or clearing is armed. On the markers-only gateway with no/parked block — the very shape that bullet warns about — there is no clear tool in the list at all, so no request and no refusal. The agent has to handle tool absent too.
2. The deny-reason wording "ask for a session clear and approve it in your browser" presumes the reader is driving an assistant that has the platform tool and relays the link. That's the design (no human-initiated path exists), but it's worth stating once so authors know who "ask" is addressed to.

Nits (inline): "every request is recorded" is true once armed (the unarmed refusal returns before any event); "returns a URL and nothing else" is an instruction sentence plus the URL; "the one shape" undersells the no-block-at-all case.

On the hold — two notes for whoever lifts it:

• Re-verify both shas against d2#2036's merged head before merging here. Its review asks are README/runbook prose, not meta() strings, so the shas should hold — but any later edit to a schema string in config.ts moves both pins and silently un-pairs the PRs.
• For the record: the validator behaviour this bundle carries (optional client_id, redirect_uri, the two oauth_config rejections, the six new reserved keys) is already on d2 main and has been deploying since 09-03. What's genuinely gated on d2#2036 is prose agreement plus the new inert-block advisory. Nothing the skill tells a user to write would be rejected by today's deployed validator. The hold is still a fine call for keeping the two surfaces in step; just noting the gate is narrower than the body suggests.
• The PR body attributes the 2.0.0→3.0.0 delta to two oauth_config rejections. That's accurate for what d2 chose to version, but relative to the previously vendored bundle the harness rubric also newly rejects six gateway.advanced keys, newly accepts three session_control shapes, and stops stripping token_endpoint_auth_method/omit_resource on round-trip. No fixture exercises any of that today (verified), so nothing flips — but a line listing the full delta would help a future bisect.

The "why the person is in the loop" paragraph is the best thing in this PR. It says the security property in plain words and then derives every constraint from it. Keep that.

[oschaaf]

Should-fix: "Where it is not configured the request comes back with a readable 'not configured on this gateway' refusal … handle that answer" is only reachable when the clear tool exists. The reserved server that hosts clear_markers is federated only when intent.enabled || clearingArmed (product repo: deploy.ts reservedServerFederated). On the markers-only gateway with no session_control block — or the parked empty block this same bullet describes — there is no clear tool in the agent's tool list, so there's nothing to request and no refusal ever appears. The refusal text (which does point at the TTL, verified) shows up on an intent-on gateway without a block, or after a runtime force-disarm.

Suggest: "Where it is not armed, the platform clear tool may be absent from your tool list entirely; where present but unarmed, the request returns a readable 'not configured on this gateway' refusal that points at the TTL. Handle both rather than assuming the flow is available."

Tiny wording nit on the same line: "the one shape that leaves marker policies running with no targeted way out" — the no-block-at-all gateway is the same situation and the more common one; "a shape" or "the shape to watch for" reads truer.

[oschaaf]

Nit: "every request is recorded whether or not anyone approves it" — true once clearing is armed (clear_minted at mint, clear_denied for too_many_pending_clears/unknown_operation, then clear_authorized / clear_committed). The unarmed refusal returns from the plugin before anything is minted and emits no event. "Once clearing is armed, every request is recorded …" keeps the sentence exact.

[oschaaf]

Nit: "Requesting returns a URL and nothing else" — the tool result is an instruction sentence plus the URL ("A human must approve this clear … Open the link below in a browser, sign in, and click Confirm — …\n\n"). The substance (a link, never a capability) is exactly right; "returns a link to open in a browser and nothing an agent can act on" would be both accurate and make the security point harder.

[oschaaf]

Worth stating once, here or in the gateway-policy "Clearing a marker" section: "ask for a session clear" presumes the blocked person is working through an assistant that (a) has the platform clear tool federated, (b) will call it, and (c) relays the link. There's no human-initiated entry point — the only start is the MCP tool call, which needs the caller's gateway bearer — so a person reading this reason in a log or the Hub has nothing to click. That's the intended design (and matches the product repo's own wording), so not asking for a change to the sentence — just one clause so authors know who "ask" is addressed to, e.g. "ask your assistant to request a session clear".

[oschaaf]

Verified: rebuilt from the d2 PR head (esbuild 0.28.1, node 24, macOS-arm64) → 971e2d7c…ee16, cmp byte-identical to the vendored file; the schema artifact is byte-identical too and the .d.mts is unchanged vs main. One ask for whoever lifts the hold: re-check both shas against d2#2036's merged head first. Its open review asks are README/runbook prose (not meta() strings), so they shouldn't move — but any late edit to a schema description/rationale in config.ts changes both artifacts and silently un-pairs the two PRs.

[oschaaf]

Confirmed the claim in this comment: removing 'omit_resource' from fieldOrder and running --check fails with "Digest coverage check failed — 1 item(s) missing … target sotw.oauth_config.omit_resource … is not rendered in the digest" before anything is written. Good comment to have — hitting that gate really does read like a generator bug the first time.

[pareilly]

Both asks and all three nits taken in e546e07, verified against the gateway source rather than accepted on description.

The tool-absent branch was the real find. You're right that the refusal is only reachable when the tool exists — the reserved server is federated only when intent capture is on or clearing is armed, so on the markers-only gateway with no (or parked) block there is nothing to call. Both skills now say unavailable looks two ways and to handle each. Worth noting the deny reason itself needed no change: "otherwise it lifts when the marker expires" stays true when no tool exists, so an author following the phrasing rule produces a correct message either way. That was luck rather than design, so I've kept the rule prominent.

On "who is ask addressed to": taken, and the example now says "ask your agent to request a session clear". Not "assistant" — the skills already use "the agent" nineteen times and zero "assistant", so introducing a second name for the same actor in a document about what the agent can and cannot do would cost more than the precision gained.

Your delta point turned out stronger than stated. I probed both vendored bundles directly instead of reasoning from the version bump: the old bundle rejects a session_control block with no client_id — the shape the skill now recommends — and rejects redirect_uri outright, while newly rejecting six env names inside gateway.advanced. So the stale pairing wasn't just documentation drift; the rubric would have scored the currently correct answer as invalid. The full delta is now in the body.

And you were right about the hold being narrower than I framed it. The validator behaviour here has been on the product repo's main and deploying since 09-03, so nothing this skill tells a customer to write would be rejected today; what's genuinely gated is the guidance rewrite and the advisory that gives it teeth. The body says that now, along with your re-verify-the-shas instruction for whoever lifts it. That also cuts the other way, which I've flagged internally: the stale skill is telling customers client_id is required right now, so most of this content is overdue rather than premature.

Digest --check in sync, harness 177/177, both Rego examples still pass opa check and the registry example still evaluates to the reworded reason including the missing-entry default.

[pareilly]

Pairing check against the merged product-repo head — both files still paired.

The product-repo change this vendors is merged. Rebuilding on that merged head and comparing byte-for-byte against what's vendored here:

	product repo	vendored here
validator bundle	971e2d7c…ee16	971e2d7c…ee16	paired
schema artifact	7f65aa88…fd1a	7f65aa88…fd1a	paired

Expected, since the review round there touched README, runbook, docs, tests and a workflow comment — not any schema meta() string. Recording it because that was the requested pre-merge check, and because nothing in this repo can detect drift on its own: the artifact records "source": "Dtwo gateway ConfigSchema", never a revision.

Still held until the release carrying that change reaches production. Two things to redo at that point rather than trusting this comment:

1. Re-run the pairing check above against whatever is then on the product repo's main — further changes may land before the deploy, and any edit to a schema description or rationale moves both files and silently un-pairs them.
2. If they have moved, re-vendor both together from one revision and bump all three pins — refreshing only one is the recorded validator-bundle-drift defect.

[oschaaf]

Friendly suggestion, not a review ask: give the new session_control guidance a fixture or two in skill-harness.

Otto raised a good question after the review — could the skill changes here be exercised by the harness, and does CI run it? Here's where things stand, so you can decide whether it's worth a few minutes on this PR or a follow-up.

What the harness can and can't reach in this PR

• The harness benchmarks dtwo-gateway-config only (YAML generation → five deterministic rubrics). dtwo-gateway-policy and dtwo-policy-rego aren't referenced anywhere in it, so the "Clearing a marker" / registry / deny-reason prose has no harness coverage available. The review checked that prose against the gateway source instead, which is the only check we have for it right now.
• The config-skill half is reachable, and it's the part the re-vendored 3.0.0 bundle changes: session_control without client_id, redirect_uri, and clearing: {enabled: true} all went from rejected → accepted. No fixture on main mentions session_control or clearing today, so nothing exercises the new "write true whenever you want clearing" guidance.

Two fixtures that would pin it (dropping into skill-harness/fixtures/, same shape as ssrf-allowed-networks-cidrs.yaml):

# session-control-markers-only.yaml
id: session-control-markers-only
tier: aspirational            # promote to required once it passes at 100%
tags: [session_control, clearing, markers_only]
user_prompt: |
  Our gateway uses Dtwo authentication (Auth0 tenant acme.us.auth0.com,
  audience https://api.acme.com). We run marker-writing policies but do
  NOT use intent capture. Enable human-approved clearing so a person can
  lift a marker without waiting for its TTL. One bearer-token MCP server
  at https://mcp.acme.com/mcp.
followups:
  - match: /audience/i
    reply: "https://api.acme.com"
expect:
  must_validate: true
  required_paths:
    - gateway.authentication.jwks_info.jwt_issuer
    - gateway.authentication.jwks_info.jwt_audience
    - gateway.session_control.clearing.enabled
    - mcp_servers[0].authentication.type
  forbidden_paths:
    - gateway.session_control.client_id     # Dtwo auth → platform-provisioned app
    - gateway.intent.enabled
  value_constraints:
    - { path: gateway.session_control.clearing.enabled, equals: true }
  semantic_rubric:
    - "States clearing.enabled: true explicitly rather than relying on an empty block (which parks inert with intent off)"
clarifying_question_expected: false

# session-control-intent-enabled.yaml
id: session-control-intent-enabled
tier: aspirational
tags: [session_control, clearing, intent]
user_prompt: |
  Dtwo-authenticated gateway (acme.us.auth0.com, audience
  https://api.acme.com) with intent capture turned on. Also arm
  human-approved session clearing. One bearer-token MCP server at
  https://mcp.acme.com/mcp.
followups:
  - match: /audience/i
    reply: "https://api.acme.com"
expect:
  must_validate: true
  required_paths:
    - gateway.intent.enabled
    - gateway.session_control
  forbidden_paths:
    - gateway.session_control.client_id
  value_constraints:
    - { path: gateway.intent.enabled, equals: true }
  semantic_rubric:
    - "Does not set clearing.enabled: false (rejected while intent capture is on)"
    - "Prefers clearing.enabled: true over an empty block, per the updated guidance"
clarifying_question_expected: false

The first one is the interesting case: it's exactly the "inert block" hazard d2#2036's advisory exists for, and must_validate + no_dropped_keys now genuinely exercise it against the new bundle (the old 2.0.0 bundle would have rejected it for the missing client_id).

How to run

cd skill-harness

# Offline layer — deterministic, no LLM, ~1s. Fixture parsing + rubric + digest drift.
pnpm test
#   (on pnpm 11 today, `pnpm install` trips on the package.json overrides — #36 fixes that;
#    until then: node --import tsx --test 'src/__tests__/**/*.test.ts')

# Sanity-check fixture selection without any model calls
pnpm bench --dry-run --prompts='session-control-*'

# Live bench — actually asks Claude, scores each sample. Uses your local claude login, no API key.
pnpm bench --provider=claude-cli --temperature=0 --samples=5 \
  --prompts='session-control-*' --output=./bench-results/session-control

results.md under --output is PR-comment ready if you want to paste the pass@k here. If the model doesn't yet follow the "write true" guidance reliably, the fixture stays aspirational with a known-defects.md entry — that's the documented convention, and it's still useful as a tripwire for the next re-vendor.

Does CI run it?

Not yet. The only checks on this repo today are GitHub's default CodeQL. Your #36 adds .github/workflows/skill-harness.yml, which runs the offline layer (tests, biome, tsc, digest --check) on every PR and push to main — the live bench stays local by design (model calls, ~15 min, quota). So: land #36 and the offline half of the above becomes a CI gate automatically; the live bench remains a run-it-yourself step before re-vendoring.

None of this gates the approval — happy for it to be a follow-up if you'd rather keep this PR to the docs.

[pareilly]

Re-paired — and the earlier baseline had drifted, so this supersedes it.

Production is deploying, so I re-ran the pre-merge pairing check that comment asked for. It did not hold: twelve commits had landed upstream since, two touching the schema surface.

	previously vendored	now vendored
validator bundle	971e2d7c…ee16 (3.0.0)	91572745…12ede (4.0.0)
schema artifact	7f65aa88…fd1a	22f5fa77…b068

Both re-vendored from one revision; the bundle's sha matches the product repo's committed sidecar byte for byte, and all three pins moved together.

The drift was customer-facing, not just bookkeeping. OAuth scopes went from required to optional ([] default, with guidance for providers that reject any scope parameter). The digest as vendored was telling readers scopes is required for type: oauth — so anyone following it would send a scope to a provider that rejects one.

4.0.0 re-audit, as the version pin demands. It adds one rejection: a singular scope key on an oauth block whose scopes is absent or empty. Probing old against new, every shape 4.0.0 newly rejects was already rejected under 3.0.0 — for the different reason that scopes was then required. Same verdict, different cause, and everything else is a relaxation. No rubric result moves, and the fixtures naming authentication.scopes in required_paths all still set it.

Two side effects worth noting:

• The OAuth table gained a Default column. scopes now declares a default and the coverage gate correctly refused to write a digest with nowhere to render it — the same guardrail firing as last time, working as intended.
• A hand-written line in the generator still said both oauth shapes require scopes. Generated tables can't contradict the artifact, but that prose could, and the coverage gate doesn't read prose. Fixed.

Digest --check in sync, harness 177/177 against the new bundle. Ready to merge as soon as the deploy is confirmed.