📝 docs(openspec): design P5-DEM public demo repositories (D-142, OQ-32)

[konih]

Spec-first design for two public demo repositories, plus an assessment of how extensible the user-resolution (provider) seam actually is. Design only — no code, no schema, 14 stories decomposed but none implemented.

This work was authored in a prior session and was sitting uncommitted and untracked in the working tree. It is committed here unchanged apart from the rebase onto current main.

The question that opened it, and the honest answer

"Does there already exist a sample GitLab repository we can test with as well as a sample GitHub repository?" — No. examples/repos/** are content layouts with no .assent/ tree; examples/packs/** are policy trees with no repo identity; gitlab.com/konrad.heimel/assent-lab is the operator's personal D-042 adoption-proof project, not a showcase; GitHub presence is zero because E10 is spec-only. So "everybody can see assent in action themselves" is currently false.

The constraint that shapes the epic

assent cannot run on a GitHub PR today. The design therefore commits to a two-tier demo contract, stated on each repo's front page:

• Tier 1 — git clone && assent test .: forge-independent, no token, no network, no IdP. Deliverable now, on both repos, via the E6 harness. This is the "everybody can see it" claim.
• Tier 2 — a live MR/PR: GitLab now, GitHub blocked on E10-S18.

The two repos are split by governance shape, not by tool — otherwise they demonstrate the same three archetypes twice. Repo 1 (assent-demo-platform, GitLab) is request a platform resource, distinguished by being referential: an ACL names a topic and a principal, so the decision cannot be made from the changed file alone — which is exactly what builtin/resource-owner and builtin/repo-file exist for and what no shipped example exercises end to end. Repo 2 (assent-demo-terraform, GitHub) is change infrastructure, distinguished by blast radius plus the opaque-change fallback, and doubles as E10-S18's live adoption target.

🔴 The finding that outlives this epic

(class, environment) binding routing is not wired, so a multi-class demo repo fails closed in both tiers on both forges. Found by reading the code against the design:

• cmd/assent/run.go:493 selectBinding fails closed on any RulesetBinding with >1 binding — its own comment says the Config class-matcher "is not wired in this lane".
• cmd/assent/test.go:366 selectBindingForTest collapses to the strictest binding (D-060) but fails closed when two bindings differ in class, packs, or require[].

Both demo repos have three classes with different require[]. Why nobody noticed: D-060 recorded the shipped packs' dev/prod split as "empirically decision-neutral for the corpus" — every shipped example is single-class with a decision-neutral environment split, so the collapse is invisible and the matcher is never missed. The demo is the first artifact needing real routing.

This lands as DEM-S00 (engine-grade · maintainer LGTM). It is wiring, not new contract — policy.Config already carries Environments/Classes as NamedMatch. Note the epic's clearest demonstration — the identical diff that APPROVEs in dev and REVIEWs in prod — is impossible in either tier today, which is why it becomes S00's sharpest acceptance test.

Reverting this PR does not close that gap. D-060 remains its standing record.

On provider extensibility

Verified verdict: the seam is genuinely good and extending it needs no core change and no fork. The wire contract is frozen and published, and extension is a two-file repo-side change read from the protected target ref — so an MR author cannot redefine their own fact semantics.

But four gaps stand between that and "easily extendable", and the spec states all four rather than demoing around them. Two are P1:

• G1 — find examples -type d -name providers returns nothing. All three shipped packs declare providers: with no host declaration, so provider_host.go:83-87 silently continues and every shipped example's provider resolves to nothing. The required path is documented nowhere.
• G2 → OQ-32 — CallHTTP sets only Content-Type; the repo-side provider schema is additionalProperties:false over {type,url,failure}; ScrubEnv/ScrubArgv refuse (?i)TOKEN|SECRET names even when explicitly configured. So no provider can call Entra ID or Keycloak directly — both need a bearer token. This is not a bug, it is ADR-0015 §7 working as designed, with a hostile-provider isolation proof resting on it. What has never been written down is the consequence: the only working shape is a broker holding the IdP credential itself. That narrows what docs/vision.md:67 promises, and OQ-32 is deliberately left unresolved — option (b), adding a credential channel, is a trust-boundary change needing its own ADR, and must not be resolved by quietly adding a header field.

The epic recommends never shipping OIDC/Keycloak/LDAP builtins (ADR-0004 §1 listed them; they never shipped): each is an unbounded auth surface entering the decision path's dependency tree for no capability HTTP lacks. Instead a four-layer ladder (L0 fixtures → L1 no-network builtins → L2 forge-groups → L3 your IdP broker) with a runnable contrib/providers/idp-groups/ reference; the L2→L3 step is two files changed, zero lines of assent rebuilt.

Operator gate

DEM-S13 is operator-gated. Creating public repositories under the PlatformRelay org is outward-facing and not covered by AGENTS.md rule 2's push grant to PlatformRelay/assent. S01–S12 are unblocked by it.

Gates

task check green locally at the branch tip (exit 0) — release-exitgate skips on PRs, so CI never runs it. Docs/spec only.

Decision rows verified intact after the rebase: D-140, D-141, D-142 all present, with #45's operator-answer closures preserved.