CHORUS/docs/development/prompt-derived-role-policy-brief.md

Prompt-Derived Role Policy Design Brief

Background

WHOOSH currently loads a curated library of role prompts at startup. These prompts already capture the intended responsibilities, guardrails, and collaboration patterns for each role. SLURP and SHHH need a consistent access-control baseline so that temporal records, UCXL snapshots, and DHT envelopes stay enforceable without depending on ad-hoc UI configuration. Today the access policies are loosely defined, leading to drift between runtime behaviour and storage enforcement.

Goals

• Use the existing prompt catalog as the authoritative source of role definitions and minimum privileges.
• Generate deterministic ACL templates that SLURP, SHHH, and distribution workers can rely on without manual setup.
• Allow optional administrator overrides via WHOOSH UI while keeping the default hierarchy intact and auditable.
• Provide a migration path so temporal/DHT writers can seal envelopes with correct permissions immediately.

Proposed Architecture

1. Prompt → Policy Mapper

• Build a WHOOSH service that parses the runtime prompt bundle and emits structured policy descriptors (per role, per project scope).
• Each descriptor should include: capability tags (read scope, write scope, pin, prune, audit), allowed UCXL address patterns, and SHHH classification levels.
• Output format: versioned JSON or YAML stored under UCXL (e.g., ucxl://whoosh:policy@global:roles/#/policy/v1).

2. Override Layer (Optional)

• WHOOSH UI can expose an editor that writes delta documents back to UCXL (…/policy-overrides/v1).
• Overrides apply as additive or subtractive modifiers; the base policy always comes from the prompt-derived descriptor.
• Store change history in UCXL so BUBBLE can audit adjustments.

3. Consumer Integrations

• SLURP: when sealing temporal/DHT envelopes, reference the policy descriptors to choose ACLs and derive role-based encryption keys.
• SHHH: load the same descriptors to provision/rotate keys per capability tier; reject envelopes that lack matching policy entries.
• WHOOSH runtime: cache the generated descriptors and refresh if prompts or overrides change; surface errors if a prompt lacks policy metadata.

Deliverables

1. Policy mapper module with tests (likely Go for WHOOSH backend; consider reusing ucxl-validator helpers).
2. Schema definition for policy documents (include example for engineer, curator, archivist roles).
3. SLURP + SHHH integration patches that read the policy documents during startup.
4. Migration script that seeds the initial policy document from the current prompt set.

Implementation Notes

• Keep everything ASCII and version the schema so future role prompts can introduce new capability tags safely.
• For MVP, focus on read/write/pin/prune/audit capabilities; expand later for fine-grained scopes (e.g., project-only roles).
• Ensure policy documents are sealed/encrypted with SHHH before storing in DHT/UCXL.
• Expose metrics/logging when mismatches occur (e.g., temporal writer cannot find a policy entry for a role).

Risks & Mitigations

• Prompt drift: If prompts change without regenerating policies, enforcement lags. Mitigate with a checksum check when WHOOSH loads prompts; regenerate automatically on change.
• Override misuse: Admins could over-provision. Mitigate with BUBBLE alerts when overrides expand scope beyond approved ranges.
• Performance: Policy lookups must be fast. Cache descriptors in memory and invalidate on UCXL changes.

Open Questions

• Do we need per-project or per-tenant policy branches, or is a global default sufficient initially?
• Should BACKBEAT or other automation agents be treated as roles in this hierarchy or as workflow triggers referencing existing roles?
• How will we bootstrap SHHH keys for new roles created solely via overrides?

References

• Existing prompt catalog: project-queues/active/WHOOSH/prompts/
• Temporal wiring roadmap: project-queues/active/CHORUS/docs/development/sec-slurp-ucxl-beacon-pin-steward.md
• Prior policy discussions (for context): project-queues/active/CHORUS/docs/progress/report-SEC-SLURP-1.1.md

Integration Plan

1. Mapper Service Stub — add a policy.NewPromptDerivedMapper module under pkg/whoosh/policy that consumes the runtime prompt bundle, emits the JSON/YAML policy envelope, and persists it via SLURP's context store (tagged under whoosh:policy).
2. SLURP Startup Hook — extend pkg/slurp/slurp.go to request the mapper output during initialisation; cache parsed ACLs and expose them to the temporal persistence manager and SHHH envelope writer.
3. SHHH Enforcement — update pkg/crypto/role_crypto_stub.go (and the eventual production implementation) to honour the generated ACL templates when issuing wrapped keys or verifying access.
4. WHOOSH Overrides UI — surface the optional override editor in WHOOSH UI, writing deltas back to UCXL as described in this brief; ensure SLURP refreshes policies on UCXL change events.
5. Testing — create end-to-end tests that mutate prompt definitions, run the mapper, and assert the resulting policies gate SLURP context retrieval and DHT envelope sealing correctly.