Falaah Falaah AI

Compliance Policy Hub

Author compliance policies in a rich-text editor, version them automatically, attest through web-checkbox confirmation, and draft faster with AI assistance.

The Policy Hub is where compliance policies are authored, reviewed, published, and attested. Every active policy has a version history, and every employee sees only the policies they’re required to attest to — filtered by category, tenure, department, or explicit assignment.

There are two distinct attestation paths, picked automatically by category:

  • Web checkbox for everything (safety training, harassment, remote work, BYOD, etc.) — because dragging every employee through DocuSign for a harassment refresher is friction theatre.
  • Legally binding e-signature for high-stakes categories (security, privacy, code of conduct, data handling, compliance, HR policy) — these will route through a vendor partnership when the feature ships. Status: coming soon. Until then, high-stakes categories also use the web-checkbox path with full audit trail.

Admins can override per-policy when the default routing doesn’t fit.

The Lifecycle

Create → Draft body (rich-text) → Publish → Assign → Attest → Track → Renew/Archive

Every step is audited. Every state change is logged with user, timestamp, and context — so when an auditor asks “when did this policy take effect and who signed it on what date,” the answer is a one-query lookup.

Creating a Policy

On /compliance/policies, click New Policy. The form asks for:

Field Purpose
Name e.g. “Information Security Policy”
Category Drives the default signing routing — see the table below
Description Short summary shown on the list page
Effective date When the policy takes effect
Review date When it should be re-reviewed (defaults to 1 year out)
Requires acknowledgment If false, the policy is informational only
Acknowledgment deadline (days) How many days from effective date the employee has to attest
Signing override (admin only) Tri-state override of the default routing

Categories and Default Routing (D8)

Category Default path Rationale
security E-signature (coming soon) ISO 27001 / SOC 2 require signed acknowledgments
privacy E-signature (coming soon) GDPR / CCPA legal defensibility
code_of_conduct E-signature (coming soon) Employment-law backstop for terminations
data_handling E-signature (coming soon) HIPAA / data-breach-notification proof
compliance E-signature (coming soon) Audit evidence
hr_policy E-signature (coming soon) Wage/leave legal compliance
safety_training Web checkbox High volume, low legal-liability tier
harassment Web checkbox Routine annual refresher
byod Web checkbox Device policy
remote_work Web checkbox Workplace policy
other Web checkbox Default for ad-hoc policies

The canonical list lives in muin.core/src/muin_core/models/hr_policy.py (SIGNING_REQUIRED_CATEGORIES frozen set). If your organization needs a category to flip paths, use the Signing Override field on the policy itself rather than changing the global list.

Authoring the Policy Body

Policies support a full rich-text editor (IS6) — same DocumentEditor component used across Muin. Formatting, headings, lists, tables, links, and inline callouts all render identically in the editor and in the attestation view the employee sees.

When you save the draft with content, Version 1 is created automatically in the same atomic operation. If the version-create step fails for any reason, the policy row is soft-deleted so you never end up with a policy that has a name but no body. Subsequent edits create new versions (2, 3, …) — old versions are retained for audit.

AI Draft Assistance

The Draft with AI button invokes Bedrock Claude with:

  • The policy name and category
  • The SOC 2 / GDPR / HIPAA controls relevant to that category (pulled from the tenant’s active frameworks)
  • Optional prompt text — “include remote-work and BYOD clauses”

The AI returns a structured draft you review and edit in the rich-text editor before publishing. The draft is never published automatically — it’s a first draft, not a shipped policy. Hallucination fences in the draft service reject invented regulation citations; anything the AI claims a regulation “requires” must be traceable to the actual framework controls in your tenant.

Limits: 5 drafts per tenant per hour to prevent runaway costs. The badge on the policy detail page shows whether the current version was AI drafted or Human authored.

Publishing and Assigning

Publishing moves a policy from draft → active. At the moment of publish, Muin:

  1. Makes the policy visible on /compliance/policies list for all users with read access
  2. Creates HumanTask(category=POLICY_ATTESTATION) fanout records for every employee in the assignment scope
  3. Sets the task action_url to /compliance/policies/:id/acknowledge so notifications deep-link straight into the attest flow
  4. Schedules reminder notifications at 3 days and 0 days before the acknowledgment deadline

Assignment scopes:

  • All employees — everyone in the tenant
  • Department(s) — employees whose department_id matches
  • Individual employees — hand-picked assignment (used for exec-only policies)

The Employee Attestation Flow

Every employee sees their pending attestations in the My Pending Compliance Work widget on the /compliance Today tab. Clicking an item opens /compliance/policies/:id/acknowledge — the employee-facing attest surface.

Already Acknowledged

The route is idempotent — if the employee has already attested, the page shows “You’re done” plus the acknowledgment timestamp. Re-visits are safe; they never double-attest.

E-Signature Path (coming soon)

When the legally binding e-signature feature ships, signing-required categories will route through a vendor-issued envelope flow with a short-lived signing URL, embedded signing widget, and webhook callback that attaches the signed PDF to the acknowledgment record. Today these categories also use the web-checkbox path with full audit trail.

Web Checkbox Path

The page shows the policy body and an I attest button. One click records the acknowledgment — no DocuSign round-trip, no extra tab.

Both paths record the same audit fields: acknowledged_at, acknowledged_by, policy version, user agent, IP. Once legally binding e-signatures ship, signing-required categories will additionally attach a signed PDF to the acknowledgment record.

Version Management

Creating a New Version

On policy detail, click New Version. The rich-text editor opens pre-filled with the current body. Edit, save, publish.

Publishing a new version:

  • Archives the old version (not deleted — retained for audit)
  • Resets the acknowledgment state for every employee — new version requires fresh attestation
  • Creates new HumanTask fanout records
  • Fires reminder notifications for the new ack cycle

The old acknowledgments remain visible on the employee’s profile for audit, labeled with the version they attested to.

The Race-Retry Semantic (R3)

Two admins editing simultaneously can both try to create Version N+1. Muin uses a compare-and-set on the version counter — the losing write retries by reading the current version and trying again. The first write wins; the second becomes Version N+2. Nobody’s work is lost.

Archiving a Policy

Archived policies stay visible on the list with an archived badge for audit purposes, but they’re no longer active — no new ack fanouts, no reminders, no inclusion in policy documentation score.

The Signing Override

The per-policy Signing Override field lets admins deviate from the category default:

  • null (default) — inherit from SIGNING_REQUIRED_CATEGORIES
  • true — force the legally binding e-signature path (when the feature ships) even if the category defaults to web-checkbox
  • false — force web-checkbox even if the category defaults to e-signature

Use cases:

  • A security category policy that’s informational-only (override → false → web checkbox)
  • A safety_training policy for C-suite only where signed proof is needed (override → true → e-signature once the feature ships)

The resolved path is exposed on GET /policies/:id/my-acknowledgment as effective_signing_required — the attestation UI reads that value directly rather than re-implementing the routing logic client-side.

Policy Summary Dashboard

The policy list page shows summary stat cards at the top:

Card What it counts
Active policies Policies with status=active
Pending acknowledgments Employees × policies with open HumanTask(category=POLICY_ATTESTATION)
Overdue Pending acknowledgments past their acknowledgment_deadline
Due for review Policies whose review_date is within 30 days

Clicking a card filters the policy list to the matching slice.

FAQs

Why does a policy require signature?

The category determines the default. If the category is in SIGNING_REQUIRED_CATEGORIES (security, privacy, code of conduct, data handling, compliance, HR policy) the default path will be the legally binding e-signature flow once it ships. These are the categories that need a legally defensible signed record for audit, breach notification, or termination proceedings. Admins can override per-policy with Signing Override. Until e-signatures ship, all categories use the web-checkbox path with full audit trail.

How do I override the default?

On the policy’s detail page, toggle Signing Override to Force signed or Force web checkbox. The change takes effect on the next acknowledgment — already-recorded acks keep their original path (they aren’t re-routed retroactively).

What happens when someone doesn’t attest on time?

At deadline - 3 days and again at deadline - 0 days, the reminder worker fires a notification to the employee and creates an overdue HumanTask for the compliance owner. The /compliance Today tab surfaces the overdue count. Overdue attestations drag the policy documentation factor of the compliance score (15% weight).

Can I edit a published policy without creating a new version?

No — published policies are immutable except for metadata (name, review date, assignment scope). Body changes always create a new version, which requires fresh attestations. This is by design: every employee attests to a specific version, and an immutable version is what the auditor asks for six months later.

What if the e-signature provider is down? (after the feature ships)

The employee sees an error on click of Review & Sign. They can retry — each retry is idempotent, so duplicate envelopes won’t accumulate. If the provider is down for an extended period, admins can temporarily flip Signing Override to false for urgent policies so employees can attest via web checkbox as a fallback.