paliad/docs/design-approval-policy-ui-2026-05-07.md

Approval-policy authoring UI — design

Task: t-paliad-154 Issue: m/paliad#13 Inventor: hilbert (2026-05-07) Branch: mai/hilbert/inventor-approval-policy Status: READY FOR REVIEW

---

§0 — One-paragraph summary

cronus shipped the t-138 4-eye backend on 2026-05-06: tables, service layer, HTTP API, audit events, the /inbox shell. The whole thing has been dormant in production since because paliad.approval_policies has zero rows, and no UI exists to author policies. m hit this hard 2026-05-07 22:55 — created a deadline expecting a request on /approvals, got nothing. This design fills the gap with two coordinated changes: (a) a backend extension to support per-partner-unit defaults layered with project-tree inheritance, both resolved most-restrictive, with an explicit 'none' sentinel for project-level opt-out; (b) a single new admin page /admin/approval-policies with a project-picker → 8-cell matrix and a partner-unit defaults section, plus in-context hints on the deadline/appointment forms when 4-eye applies. v1 ships seeded conservative defaults for every existing partner unit so the gate starts working on next deploy without per-project authoring.

---

§1 — What's already built (verified live, 2026-05-07)

cronus's t-138 implementation is complete and merged. Verified premises:

• Schema (migration 054, applied): paliad.approval_policies with (id, project_id, entity_type, lifecycle_event, required_role, created_at, updated_at, created_by) + UNIQUE composite on (project_id, entity_type, lifecycle_event). RLS enforces SELECT via can_see_project(project_id), WRITE via global_role='global_admin'. Read-only check on the live DB via the migration file at internal/db/migrations/054_approvals.up.sql:75.

• Required-role enum (post-059): partner | of_counsel | associate | senior_pa | pa. The 'lead' → 'partner' rename happened in migration 059 (t-148, kepler) — verified at internal/db/migrations/059_profession_vs_responsibility.up.sql:166-172. Mirrors paliad.users.profession (firm-wide career tier), not paliad.project_teams.responsibility (project-level role) — the gate keys on profession because that's how the strict ladder paliad.approval_role_level() works.

• HTTP API (admin-gated): three handlers in internal/handlers/approvals.go register at internal/handlers/handlers.go:421-426:

  • GET /api/projects/{id}/approval-policies → list
  • PUT /api/projects/{id}/approval-policies/{entity_type}/{lifecycle} → upsert
  • DELETE /api/projects/{id}/approval-policies/{entity_type}/{lifecycle} → clear

  All three wrapped with auth.RequireAdminFunc(users, ...).

• LookupPolicy (internal/services/approval_service.go:69-83) does not walk the project tree today. It SELECTs the exact (project_id, entity_type, lifecycle_event) tuple and returns the row or nil. Tree inheritance is brand-new in this design.

• Audit: approval-request submission and decisions emit paliad.project_events rows; policy CRUD does not. Verified at internal/services/approval_service.go:255 (request emits) — no insertProjectEvent call inside UpsertPolicy/DeletePolicy at lines 913-948.

• Partner-unit substrate (t-139, migration 055, applied):

  • paliad.partner_units (id, name, lead_user_id, office, ...) — verified at internal/services/partner_unit_service.go:29.
  • paliad.project_partner_units (project_id, partner_unit_id, derive_grants_authority, derive_unit_roles) — verified at internal/db/migrations/055_hierarchy_aggregation.up.sql:47.

• Admin index pattern: /admin is a card-grid of single-purpose admin sub-pages — team, partner-units, audit-log, email-templates, event-types, broadcasts. Verified at frontend/src/admin.tsx:60-91. New approval-policy card slots into the same grid.

• Migration tracker: last applied is 061 (paliad.user_card_layouts). Next is 062 — this design's migration.

---

§2 — m's locked decisions (2026-05-07 23:00)

12 questions surfaced via AskUserQuestion (per dogma, not as a markdown list). Locked verbatim — quoted as-asked + answer:

Q1 — Surface placement

Where should approval policies be authored? The backend admin-gates the CRUD endpoints, so anywhere we surface authoring is admin-only by definition.

Locked: Admin page only. New /admin/approval-policies card on the admin index. Single page with two sections: (a) Partner-unit defaults, (b) Project picker → 8-cell matrix. Per-project tab is out. Project visibility into effective rules happens at form-time (Q12 below), not as a permanent tab.

Q2 — Default-policy concept

With ~30 projects and 8 cells each, authoring is tedious. Should we add firm-wide defaults that individual projects override?

Locked: Per partner-unit defaults. Schema gets a nullable partner_unit_id, project_id becomes nullable, XOR check enforces a row applies to one or the other. Reuses the t-139 partner-unit infra. No firm-wide defaults — one less concept.

Q3 — Multi-unit conflict resolution

A project attached to multiple partner units with conflicting unit defaults — e.g. Munich Lit unit defaults to deadline:create=partner, Düsseldorf to deadline:create=associate. What does the gate require?

Locked: Most-restrictive wins. Take MAX(approval_role_level) across all unit defaults for the project. Conservative — 4-eye exists to prevent quiet errors, the higher bar wins.

Q4 — Tree inheritance

Projects also live in a tree. Should an ancestor project's policy inherit DOWN the project tree to descendants when they have no own row, or only via partner-unit defaults?

Locked: Both — tree inheritance AND unit defaults. Three sources contribute to the candidate set: project-specific rows, ancestor rows, unit defaults.

Q5 — Cross-source precedence

When tree-inheritance and unit-defaults both produce a candidate, which wins?

Locked: Most-restrictive across ALL sources. Project-specific row overrides outright (any value, including 'none'). When no project row, take MAX(level) across all ancestor rows + all unit defaults. Symmetric with the multi-unit rule.

Q6 — Explicit suppression sentinel

A project-specific row always wins. To set 'this project explicitly bypasses 4-eye on deadline:create' overriding a partner-unit default of 'partner', we need a sentinel.

Locked: 'none' value in required_role enum. Add 'none' to the CHECK constraint. Cell renders as "Keine Genehmigung erforderlich". Project row with required_role='none' returns nil from LookupPolicy — suppresses defaults explicitly. Single column, single concept.

Q7 — Soft-disable vs delete

Per-policy enable/disable toggle vs delete-only. With audit-log emission already locked in (Q8), do we still need soft-disable?

Locked: Delete-only. One row = one rule. "This rule used to apply" is answered by the audit log. KISS.

Q8 — Audit emission

Should policy changes emit project_events?

Locked: Only on /admin/audit-log, not on per-project /verlauf. New event types approval_policy_set and approval_policy_cleared emitted via the existing audit-log path (not via the project-events union). Project verlauf stays focused on entity-level history.

Q9 — Empty-state on /inbox

When admin opens /inbox and pending list is empty AND no policies exist, show a one-tap nudge?

Locked: Yes — admin-only card. Conditional on me.global_role === 'global_admin' && pending.length === 0 && !any_policies_exist. Card links to /admin/approval-policies. Solves the discoverability gap m hit.

Q10 — Bulk-apply

Bulk action on the admin page so an admin can fan a Mandant's matrix down to its 12 sub-projects without 96 clicks?

Locked: Yes — "Auf Unterprojekte anwenden" button per project row. Click → confirm modal listing affected descendants → applies the source project's full matrix to all descendants. Idempotent.

Q11 — Seed defaults on first deploy

Should v1 ship seeded defaults, or strictly opt-in?

Locked: Seed conservative defaults for every partner_unit. Migration inserts 8 rows per existing partner_unit:

entity	lifecycle	required_role
deadline	create	associate
deadline	update	associate
deadline	delete	associate
deadline	complete	none
appointment	create	associate
appointment	update	associate
appointment	delete	associate
appointment	complete	none

Rationale: marking-as-done is low-risk; the planning ops (create/edit/delete the date itself) need 4-eye. none on complete is an explicit "no gate" sentinel, not a missing row — so MAX-across-sources still works correctly.

Q12 — Mobile shape

8-cell matrix is too wide for narrow viewports.

Locked: Two stacked sections — Fristen, Termine, each as 4-row list. On viewports ≥ 700px: 2-row × 4-col matrix. On viewports < 700px: vertical section per entity_type with full-width dropdown rows.

Q13 — Form-time hint visibility

Should we surface 4-eye to users authoring deadlines, before they save?

Locked: Yes — hint on the deadline-form. Above the Speichern button on /projects/{id}/deadlines/new and /projects/{id}/appointments/new, render: "4-Augen-Prüfung erforderlich: nach dem Speichern wird ein Genehmigungsantrag (associate-Level) ausgelöst." Pulled from new GET /api/projects/{id}/approval-policies/effective endpoint at form load.

---

§3 — Backend extensions

§3.1 — Migration 062

internal/db/migrations/062_approval_policy_unit_defaults.up.sql:

-- t-paliad-154: approval-policy authoring UI substrate.
--
-- Extends t-138's paliad.approval_policies with:
--   1. partner_unit_id column for unit-default rows (XOR with project_id)
--   2. 'none' sentinel value for required_role (explicit suppression)
--   3. paliad.approval_policy_effective() resolver — tree + unit + most-restrictive
--   4. Conservative seed defaults for every existing partner_unit

-- 1. partner_unit_id column + nullable project_id + XOR check.
ALTER TABLE paliad.approval_policies
    ALTER COLUMN project_id DROP NOT NULL,
    ADD COLUMN partner_unit_id uuid
        REFERENCES paliad.partner_units(id) ON DELETE CASCADE,
    ADD CONSTRAINT approval_policies_scope_xor CHECK (
        (project_id IS NOT NULL AND partner_unit_id IS NULL) OR
        (project_id IS NULL AND partner_unit_id IS NOT NULL)
    );

-- Replace UNIQUE (project_id, ...) with two partial unique indexes since
-- project_id is now nullable.
ALTER TABLE paliad.approval_policies
    DROP CONSTRAINT IF EXISTS approval_policies_project_id_entity_type_lifecycle_event_key;

CREATE UNIQUE INDEX approval_policies_project_unique
    ON paliad.approval_policies (project_id, entity_type, lifecycle_event)
    WHERE project_id IS NOT NULL;

CREATE UNIQUE INDEX approval_policies_unit_unique
    ON paliad.approval_policies (partner_unit_id, entity_type, lifecycle_event)
    WHERE partner_unit_id IS NOT NULL;

CREATE INDEX approval_policies_unit_idx
    ON paliad.approval_policies (partner_unit_id);

-- 2. 'none' sentinel.
ALTER TABLE paliad.approval_policies
    DROP CONSTRAINT IF EXISTS approval_policies_required_role_check;
ALTER TABLE paliad.approval_policies
    ADD CONSTRAINT approval_policies_required_role_check
    CHECK (required_role IN (
        'partner', 'of_counsel', 'associate', 'senior_pa', 'pa', 'none'
    ));

-- approval_role_level('none') already returns 0 (the ELSE branch). No
-- function change needed.

-- 3. Resolver function.
--
-- Returns the effective policy for (project, entity_type, lifecycle):
--   1. project-specific row → wins outright (any value including 'none')
--   2. else MAX(approval_role_level) across:
--        - all ancestor project rows on the path
--        - all unit-default rows for partner units attached to project
--   3. else NULL (no candidates) → no policy applies
--
-- Returns at most one row. Caller can detect "no policy" via empty result.
CREATE OR REPLACE FUNCTION paliad.approval_policy_effective(
    p_project_id  uuid,
    p_entity_type text,
    p_lifecycle   text
) RETURNS TABLE (
    required_role text,
    source        text,         -- 'project' | 'ancestor' | 'unit_default'
    source_id     uuid          -- project_id for project/ancestor, partner_unit_id for unit_default
)
LANGUAGE plpgsql STABLE AS $$
BEGIN
    -- Step 1: project-specific row.
    RETURN QUERY
    SELECT ap.required_role, 'project'::text, ap.project_id
      FROM paliad.approval_policies ap
     WHERE ap.project_id = p_project_id
       AND ap.entity_type = p_entity_type
       AND ap.lifecycle_event = p_lifecycle;
    IF FOUND THEN
        RETURN;
    END IF;

    -- Step 2: MAX across ancestor + unit_default.
    RETURN QUERY
    WITH path AS (
        SELECT string_to_array(p.path, '.')::uuid[] AS ids
          FROM paliad.projects p WHERE p.id = p_project_id
    ),
    ancestor_rows AS (
        SELECT ap.required_role,
               'ancestor'::text AS src,
               ap.project_id AS sid,
               paliad.approval_role_level(ap.required_role) AS lvl
          FROM paliad.approval_policies ap, path
         WHERE ap.project_id = ANY(path.ids)
           AND ap.project_id <> p_project_id
           AND ap.entity_type = p_entity_type
           AND ap.lifecycle_event = p_lifecycle
    ),
    unit_rows AS (
        SELECT ap.required_role,
               'unit_default'::text AS src,
               ap.partner_unit_id AS sid,
               paliad.approval_role_level(ap.required_role) AS lvl
          FROM paliad.approval_policies ap
          JOIN paliad.project_partner_units ppu
            ON ppu.partner_unit_id = ap.partner_unit_id
         WHERE ppu.project_id = p_project_id
           AND ap.entity_type = p_entity_type
           AND ap.lifecycle_event = p_lifecycle
    )
    SELECT a.required_role, a.src, a.sid
      FROM (SELECT * FROM ancestor_rows
            UNION ALL
            SELECT * FROM unit_rows) a
     ORDER BY a.lvl DESC, a.src ASC  -- 'ancestor' < 'unit_default' alphabetically; ancestor wins ties for stable attribution
     LIMIT 1;
END;
$$;

COMMENT ON FUNCTION paliad.approval_policy_effective(uuid, text, text) IS
    'Effective approval policy resolver (t-paliad-154). '
    'project-specific row wins outright; else MAX(level) across ancestors '
    'and unit-defaults attached to project; else no policy.';

-- 4. Seed conservative defaults for every existing partner_unit.
INSERT INTO paliad.approval_policies (
    project_id, partner_unit_id, entity_type, lifecycle_event, required_role
)
SELECT NULL, pu.id, t.entity_type, t.lifecycle_event, t.required_role
  FROM paliad.partner_units pu
  CROSS JOIN (
    VALUES
        ('deadline',    'create',   'associate'),
        ('deadline',    'update',   'associate'),
        ('deadline',    'delete',   'associate'),
        ('deadline',    'complete', 'none'),
        ('appointment', 'create',   'associate'),
        ('appointment', 'update',   'associate'),
        ('appointment', 'delete',   'associate'),
        ('appointment', 'complete', 'none')
  ) AS t(entity_type, lifecycle_event, required_role)
ON CONFLICT DO NOTHING;

062_approval_policy_unit_defaults.down.sql reverses each step (deletes seeded rows, drops the function, drops indexes, drops the column + constraint, restores the original UNIQUE + CHECK).

§3.2 — Service-layer changes

internal/services/approval_service.go changes (additive — existing callers keep working):

• Rewire LookupPolicy to call the resolver. New body:

  func (s *ApprovalService) LookupPolicy(ctx, tx, projectID, entityType, lifecycleEvent) (*models.ApprovalPolicy, error) {
      var row struct {
          RequiredRole string    `db:"required_role"`
          Source       string    `db:"source"`
          SourceID     uuid.UUID `db:"source_id"`
      }
      q := `SELECT required_role, source, source_id
              FROM paliad.approval_policy_effective($1, $2, $3)`
      err := txOrDB(tx, s.db).GetContext(ctx, &row, q, projectID, entityType, lifecycleEvent)
      if errors.Is(err, sql.ErrNoRows) || row.RequiredRole == "none" {
          return nil, nil  // no policy applies
      }
      if err != nil { return nil, fmt.Errorf("lookup approval policy: %w", err) }
      // Synthetic ApprovalPolicy — preserves the calling contract.
      return &models.ApprovalPolicy{
          ProjectID:      projectID,
          EntityType:     entityType,
          LifecycleEvent: lifecycleEvent,
          RequiredRole:   row.RequiredRole,
      }, nil
  }
  

  The submit/decide chain at lines 142-380 continues to work unchanged. 'none' returning nil means: project explicitly opted out, no request is created on save.

• New GetEffectivePoliciesMatrix(ctx, projectID) returns 8 rows (one per entity_type × lifecycle_event), each with attribution. Used by the admin page and the form-hint endpoint.

  type EffectivePolicy struct {
      EntityType     string
      LifecycleEvent string
      RequiredRole   *string  // nil if no policy
      Source         *string  // nil if no policy
      SourceID       *uuid.UUID
  }
  func (s *ApprovalService) GetEffectivePoliciesMatrix(ctx, projectID) ([]EffectivePolicy, error)
  

  Implementation: 8 calls to the resolver in a single round-trip via unnest() join, or a small batch loop — both fine for ≤8 cells.

• Extend UpsertPolicy signature to accept partnerUnitID *uuid.UUID alongside projectID *uuid.UUID. Existing callers pass projectID + nil. New callers (unit-default endpoints) pass nil + unit ID.

  func (s *ApprovalService) UpsertPolicy(ctx, callerID,
      projectID, partnerUnitID *uuid.UUID,
      entityType, lifecycle, requiredRole string) (*models.ApprovalPolicy, error)
  

  Same for DeletePolicy. Validates exactly one of (projectID, partnerUnitID) is set.

• New ApplyMatrixToDescendants(ctx, callerID, sourceProjectID, targetIDs []uuid.UUID): copies all eight rows of sourceProjectID's effective matrix to each targetIDs[i] as project-specific rows. Inside one transaction. Validates targetIDs are actual descendants via the ltree path predicate. Returns the count of (project, cell) writes performed. Skips cells where source is 'none' and target already has no row (idempotent). Emits one audit-log event per write.

• Audit emission in UpsertPolicy + DeletePolicy + ApplyMatrixToDescendants: call existing AuditService.Record (the same path /admin/audit-log uses). New event type strings: approval_policy_set, approval_policy_cleared. Metadata: scope (project|partner_unit), scope_id, entity_type, lifecycle, old_required_role (for set), new_required_role (for set). The audit service already handles JSON metadata; no schema change.

  No project_events emission (per Q8 lock-in). Project verlauf stays focused on entity-level lifecycle.

§3.3 — HTTP handlers

internal/handlers/approvals.go extensions:

• Existing routes stay at handlers.go:421-426 (gated by RequireAdminFunc).

• New unit-default routes (also RequireAdminFunc-gated, registered in the same admin block at handlers.go:386-427):

  • GET /api/admin/partner-units/{unit_id}/approval-policies — list all rows for that unit.
  • PUT /api/admin/partner-units/{unit_id}/approval-policies/{entity_type}/{lifecycle} — upsert.
  • DELETE /api/admin/partner-units/{unit_id}/approval-policies/{entity_type}/{lifecycle} — clear.
  • GET /api/admin/approval-policies/seeded — quick existence check used by the /inbox admin nudge ("are any policies set firm-wide?").

• New endpoint for matrix view (admin page):

  • GET /api/admin/approval-policies/matrix?project_id=... — returns []EffectivePolicy (8 rows with attribution).

• New endpoint for form hint (gateOnboarded, NOT admin-only — every user authoring a deadline needs to see this):

  • GET /api/projects/{id}/approval-policies/effective?entity_type=deadline&lifecycle=create — returns one EffectivePolicy row.

• New endpoint for bulk apply:

  • POST /api/admin/approval-policies/apply-to-descendants — body {source_project_id: uuid, target_project_ids: [uuid, ...]}. Validates, applies, returns counts.

• New endpoint for project tree (admin page picker — already exists in part):

  • GET /api/admin/projects/tree-flat — flat array of all projects with id, name, parent_id, depth, path for the picker. Reuses ProjectService.ListAllForAdmin (already present at internal/services/project_service.go — admin-scoped tree).

• New page handler:

  • GET /admin/approval-policies → dist/admin-approval-policies.html (server-static shell, hydrated on load).

---

§4 — Frontend

§4.1 — Admin page /admin/approval-policies

New files:

• frontend/src/admin-approval-policies.tsx — page shell. Sections:

  1. Header: "Genehmigungsrichtlinien" + tool-subtitle.
  2. "Partner-Unit-Standards" — accordion list of partner units (fetched from /api/partner-units). Each row expandable into the 8-cell matrix (Fristen × 4 lifecycle, Termine × 4 lifecycle), each cell a <select> with options partner | of_counsel | associate | senior_pa | pa | none | ❌ keine Regel (last = delete the row).
  3. "Projekt-spezifisch" — project picker (search + flat tree dropdown reusing ProjectIndentRow component from t-149). Below, the same 8-cell matrix for the selected project, each cell showing the effective value with a small attribution chip: Projekt (own row, dark) / Geerbt von Mandant Acme Corp (light, italic) / Standard von Partner Unit Munich Lit (light, italic) / Keine Regel (faint).
  4. "Auf Unterprojekte anwenden" button per project row, opens confirm modal with descendant list.

• frontend/src/client/admin-approval-policies.ts — orchestration. Fetches partner-units, project tree, matrix on selection. Saves on cell change (PUT with required_role; DELETE when set to "keine Regel"). Re-fetches matrix after save for fresh effective view. Bulk-apply confirm modal + POST.

§4.2 — Admin index card

frontend/src/admin.tsx: add a new card to the available section:

<a href="/admin/approval-policies" className="card card-link">
  <div className="card-icon" dangerouslySetInnerHTML={{ __html: ICON_SHIELD }} />
  <h2 data-i18n="admin.card.approval_policies.title">Genehmigungspflichten</h2>
  <p data-i18n="admin.card.approval_policies.desc">4-Augen-Prüfung pro Projekt und Partner Unit konfigurieren.</p>
</a>

ICON_SHIELD (new SVG) — small shield icon, matches the visual weight of ICON_USERS / ICON_BUILDING.

§4.3 — /inbox empty-state nudge

frontend/src/inbox.tsx: extend the <div className="entity-empty" id="inbox-empty"> block with a hidden admin-only sub-block:

<div className="inbox-admin-nudge" id="inbox-admin-nudge" style="display:none">
  <h3 data-i18n="inbox.empty.admin.title">Noch keine Richtlinien aktiv?</h3>
  <p data-i18n="inbox.empty.admin.body">Konfiguriere, welche Lifecycle-Events 4-Augen-Prüfung erfordern.</p>
  <a href="/admin/approval-policies" className="btn-primary btn-cta-lime" data-i18n="inbox.empty.admin.cta">
    Genehmigungspflichten konfigurieren
  </a>
</div>

frontend/src/client/inbox.ts: when rendering empty state, fire /api/admin/approval-policies/seeded. If response says {any: false} AND user is global_admin, reveal the nudge. Otherwise hide.

§4.4 — Form-time hint on deadline + appointment new/edit

frontend/src/deadlines-new.tsx + frontend/src/appointments-new.tsx (also the edit forms): add a hint container above the form-actions:

<div className="approval-hint" id="approval-hint" style="display:none">
  <span className="approval-hint-icon" dangerouslySetInnerHTML={{ __html: ICON_SHIELD_SMALL }} />
  <span id="approval-hint-text" />
</div>

Client TS: on form load, GET /api/projects/{project_id}/approval-policies/effective?entity_type=deadline&lifecycle=create (or update for edit). If result is non-null and required_role !== 'none', fill the hint:

4-Augen-Prüfung erforderlich: nach dem Speichern wird ein Genehmigungsantrag (associate-Level) ausgelöst. Geerbt von Partner Unit Munich Lit.

Same for appointments.

§4.5 — Mobile shape

CSS in frontend/src/styles/global.css:

/* Desktop: 2-row × 4-col matrix */
.approval-matrix {
    display: grid;
    grid-template-columns: 8rem repeat(4, 1fr);
    gap: 0.5rem;
}

@media (max-width: 700px) {
    .approval-matrix { display: block; }
    .approval-matrix-section {
        margin-bottom: 1.5rem;
    }
    .approval-matrix-section h3 {
        margin: 0 0 0.5rem 0;
        font-size: 1.05rem;
    }
    .approval-matrix-row {
        display: flex;
        align-items: center;
        justify-content: space-between;
        padding: 0.5rem 0;
        border-bottom: 1px solid var(--paliad-border-soft);
    }
    .approval-matrix-row select { width: 50%; }
}

The TSX renders BOTH structures (matrix grid + section list); CSS toggles based on viewport. Same pattern as the entity-table → entity-list mobile flip in frontend/src/client/projects-detail.ts.

§4.6 — i18n keys

~75 new keys in frontend/src/client/i18n.ts (DE primary, EN secondary). Major buckets:

• admin.card.approval_policies.title / .desc
• approvals.policy.heading / .subtitle / .empty
• approvals.policy.section.units / .projects
• approvals.policy.entity.deadline / .appointment
• approvals.policy.lifecycle.create / .update / .complete / .delete
• approvals.policy.required.partner / .of_counsel / .associate / .senior_pa / .pa / .none / .no_rule
• approvals.policy.source.project / .ancestor / .unit_default
• approvals.policy.bulk.cta / .modal.title / .modal.confirm / .modal.cancel / .modal.target_count / .modal.affected_list
• approvals.policy.unit_picker.placeholder / .project_picker.placeholder
• approvals.policy.cell.save_msg / .delete_msg / .error_msg
• inbox.empty.admin.title / .body / .cta
• deadlines.form.approval_hint.create / .update
• appointments.form.approval_hint.create / .update
• approvals.policy.audit.set / .cleared (for /admin/audit-log rendering)

---

§5 — Resolution semantics (worked examples)

Helps the implementer + reviewers reason about edge cases.

Example A — straight unit default

Setup: Project P attached to one partner unit U. U has unit-default deadline:create=associate. P has no own row, no ancestor with a row.

Effective for P, deadline:create:

• Step 1: no project row.
• Step 2: ancestor_rows = ∅. unit_rows = [{associate, level=3}]. MAX = associate.
• Result: (required_role='associate', source='unit_default', source_id=U.id).

LookupPolicy returns &ApprovalPolicy{RequiredRole: "associate", ...}. SubmitCreate creates a pending request needing associate sign-off.

Example B — most-restrictive across two unit defaults

Setup: Project P attached to U1 (deadline:create=partner) and U2 (deadline:create=associate). No project row, no ancestor row.

Effective for P, deadline:create:

• Step 1: no project row.
• Step 2: unit_rows = [{partner, lvl=5}, {associate, lvl=3}]. MAX = partner.
• Result: (required_role='partner', source='unit_default', source_id=U1.id).

Example C — most-restrictive across tree + unit

Setup: Project hierarchy: Mandant M (deadline:create=of_counsel) → Litigation L → Patent P. P attached to unit U (deadline:create=partner).

Effective for P, deadline:create:

• Step 1: no row on P.
• Step 2: ancestor_rows = [{of_counsel, lvl=4 (from M)}]. unit_rows = [{partner, lvl=5}]. MAX = partner.
• Result: (required_role='partner', source='unit_default', source_id=U.id).

Example D — explicit suppression at project level

Setup: Same as Example C, but admin sets P's own row to required_role='none' (carve-out for this single Patent — e.g. a low-stakes auxiliary case).

Effective for P, deadline:create:

• Step 1: project row exists with required_role='none'. RETURN.
• Result: (required_role='none', source='project', source_id=P.id).

LookupPolicy returns nil (the 'none' short-circuit). SubmitCreate skips.

Example E — most-restrictive incl. ancestor

Setup: Mandant M (deadline:create=partner). Litigation L below M, no own row, attached to unit U (deadline:create=pa).

Effective for L, deadline:create:

• Step 1: no row on L.
• Step 2: ancestor_rows = [{partner, lvl=5}]. unit_rows = [{pa, lvl=1}]. MAX = partner.
• Result: (required_role='partner', source='ancestor', source_id=M.id).

The Mandant-level rule cascades down — the typical "set once at the client root" pattern.

---

§6 — Implementation phasing

Single PR (~3500-4500 LoC). Five commits, ordered for readability:

1. Migration 062 + resolver function + seed. No Go code change. Schema is forward-compatible: existing LookupPolicy (still scanning the table directly) keeps working until commit 2 swaps it. Verify migration with TEST_DATABASE_URL + reset.

2. ApprovalService rewire. New LookupPolicy body via resolver, new GetEffectivePoliciesMatrix, extended UpsertPolicy/DeletePolicy signatures, new ApplyMatrixToDescendants, audit emission. Unit tests (table-driven): resolver fall-through cases A-E above; bulk-apply idempotency; 'none' short-circuit; XOR check.

3. HTTP handlers. Wire new admin routes + form-hint endpoint + matrix endpoint. Hand-roll models.ApprovalPolicy extensions (PartnerUnitID, Source, SourceID nullable fields). Update existing handleListApprovalPolicies to return matrix shape (with attribution) instead of raw rows.

4. Frontend admin page. admin-approval-policies.tsx + .ts. Cells render with attribution chips. Bulk-apply confirm modal. Build wires the new bundle into frontend/build.ts. CSS for the matrix grid + mobile sections.

5. Frontend touch-ups + i18n. Admin index card. Inbox empty-state admin nudge. Deadline/appointment form hints (/api/projects/{id}/approval-policies/effective call + hint render). ~75 i18n keys DE+EN. CSS finalization.

Optional split point: 1+2+3 (backend + schema, "policies authoring works via curl") and 4+5 (UI). Recommended single PR — 4+5 are the part that makes the feature reachable to m, and shipping backend-only re-exposes the issue m hit.

---

§7 — Tests

Backend (Go, table-driven):

• approval_service_test.go extensions for the resolver:
  • Project row only → returns project row.
  • Project row 'none' → returns nil from LookupPolicy.
  • Two unit defaults → most-restrictive.
  • Ancestor row + unit default → most-restrictive across both.
  • Project row + ancestor + unit defaults → project row wins.
  • No candidates → returns nil.
  • 'none' as unit-default value (low-priority — unusual but allowed) → loses to any non-none.
• ApplyMatrixToDescendants tests:
  • Source has 8 cells → target gets 8 cells.
  • Source has 5 cells (3 cleared) → target gets 5 cells; existing target rows for the other 3 are deleted (idempotent fanout, not append).
  • Target is not actually a descendant → returns ErrInvalidInput.
  • Self-target (target == source) → no-op.
• UpsertPolicy XOR validation: both NULL → ErrInvalidInput; both set → ErrInvalidInput.
• Audit emission: each set/clear writes one paliad.audit_log row with the right event type + scope.

Live-DB integration tests (TEST_DATABASE_URL):

• Migration 062 up + seed populates 8 rows × N partner_units. Down reverses. Idempotent on re-up.
• Resolver function returns expected attribution for the 5 worked examples above.

Frontend:

• admin-approval-policies smoke tests (Playwright): load page, select partner unit, change a cell, verify save → DB. Select project, verify attribution chips. Bulk-apply happy path.
• Form-hint on /projects/{id}/deadlines/new shows when policy applies, hides when it doesn't.

---

§8 — Trade-offs flagged

1. Seed defaults touch live data on first deploy. Every existing partner_unit gains 8 policy rows. m's locked-in choice (Q11) — but worth flagging that the moment migration 062 runs in production, the 4-eye gate becomes active for every project attached to a partner unit. Mitigation: deploy after announcing to the team. Conservative associate baseline means most users (associate, of_counsel, partner) can both submit AND approve, so the operational impact is "your save creates a pending request that any teammate can sign off in /inbox" rather than "your save is blocked". The bell-icon + sidebar badge from t-138 surfaces it.

2. Seed 'none' on complete is structurally invisible. A unit-default of 'none' always loses MAX to any non-none source (level 0 vs ≥1). So the seed appointment.complete=none rows are essentially "no rule" — they don't appear in LookupPolicy results. We seed them anyway for UI consistency: when an admin opens the matrix, they see 8 cells filled with values, not 4 cells filled + 4 cells empty. Documenting this as intentional.

3. 'ancestor' source attribution can be ambiguous when multiple ancestors have rows. The resolver picks the highest-level row; if Mandant=of_counsel and Litigation=partner, attribution surfaces source='ancestor', source_id=Litigation. The Mandant rule is silently overridden. The UI chip says "Geerbt von Litigation X" with no hint that the Mandant also has a rule. Cost: minor — admin can navigate to the Mandant's matrix and see its row directly. Mitigation option (deferred): the matrix-endpoint for the admin page returns the FULL stack of contributing rows per cell, so the chip can say "Strengste von 3 Quellen". Worth doing if v1 attribution feels confusing in practice.

4. Audit lives only in /admin/audit-log, not in project verlauf. Per Q8 lock-in. Minor side effect: a non-admin user wondering "why does my deadline now need approval?" can't see the policy-set event on the project's verlauf. They have to check the deadline-form hint (which says "Geerbt von Partner Unit Munich Lit") and ask an admin for the change history. Acceptable trade-off — most users don't need policy change history, only admins who set them.

5. Bulk-apply destroys target's existing project-specific rows for the 8 cells. Idempotent fanout means setting source to "matrix M" makes targets match M, including DELETE of any pre-existing target rows that aren't in M. This is by design (otherwise re-applying a partially- reduced source wouldn't actually reduce). Confirm modal lists the affected rows clearly: "12 Projekte, 8 Felder pro Projekt, ggf. bestehende Werte überschrieben". One audit-log row per write so the change is fully traceable.

6. Mobile section list duplicates the matrix data structure in the DOM. TSX renders both the grid table and the stacked sections; CSS toggles based on viewport. Slight DOM bloat (16 cells × 2 = 32 form nodes per partner unit) but matches the entity-table → entity-list pattern already used elsewhere. Alternative (single DOM rendered responsively via flex/grid-flow) is uglier in TSX.

---

§9 — Files the implementer will touch

Backend (Go):

• internal/db/migrations/062_approval_policy_unit_defaults.up.sql (new)
• internal/db/migrations/062_approval_policy_unit_defaults.down.sql (new)
• internal/services/approval_service.go (rewire LookupPolicy, add GetEffectivePoliciesMatrix, ApplyMatrixToDescendants, extend UpsertPolicy/DeletePolicy)
• internal/services/approval_service_test.go (new resolver tests, bulk-apply tests, XOR tests)
• internal/models/approval.go (extend ApprovalPolicy with optional PartnerUnitID, Source, SourceID)
• internal/handlers/approvals.go (new unit-default + matrix + form-hint + bulk-apply handlers)
• internal/handlers/handlers.go (route registration for the new endpoints + /admin/approval-policies page)

Frontend (TS/TSX):

• frontend/src/admin-approval-policies.tsx (new)
• frontend/src/client/admin-approval-policies.ts (new)
• frontend/src/admin.tsx (add card)
• frontend/src/inbox.tsx (admin-nudge block)
• frontend/src/client/inbox.ts (gate + reveal nudge)
• frontend/src/deadlines-new.tsx + frontend/src/client/deadlines-new.ts (hint render)
• frontend/src/appointments-new.tsx + frontend/src/client/appointments-new.ts (hint render)
• frontend/src/styles/global.css (matrix grid + mobile sections + attribution chip)
• frontend/src/client/i18n.ts (~75 new keys × 2 langs)
• frontend/build.ts (new bundle entry: admin-approval-policies)

Estimate: ~3500-4500 LoC (matches t-138 + t-144 design phases — small admin page, small migration, mostly mechanical wiring + CSS + i18n).

---

§10 — Recommended implementer

Pattern-fluent Sonnet — substrate is well-trodden:

• Admin-page pattern → frontend/src/admin-partner-units.tsx is the canonical reference (partner-unit picker → details panel; same shape here with project picker → matrix panel).
• Project-detail edit-in-place → client/projects-detail.ts for the <select>-on-row-click affordance pattern.
• ltree path-walk in SQL → internal/services/visibility.go and the existing paliad.can_see_project() are the reference pattern.
• Audit emission → internal/services/audit_service.go (already plumbed).
• Form-hint above Speichern → similar to the t-148 profession hint on frontend/src/projects-detail.tsx:130 (team-profession-hint).

NOT cronus per memory directive (paliad). NOT noether (parked on t-151 and t-144). NOT godel (just fired on t-149). NOT hilbert (me) — I'm parked after this design; head decides if I take the coder shift on the same worktree (mai/hilbert/inventor-approval-policy) or hands it to a fresh coder.

---

§11 — Out of scope (deferred to follow-ups)

• Per-policy time-window — "this rule applies only Mon–Fri 9–17, after hours skip 4-eye". Some firms do this. Deferred: another column would be cheap, but no signal yet that anyone wants it.
• Per-user exemptions — "Alice is on PTO, route around her". Same shape as today's decision_kind='admin_override' escape hatch — already available via global_admin.
• Multi-step approvals — "needs partner THEN of_counsel sign-off". cronus's t-138 is single-step by design (Q3 of t-138 locked it). Not in scope here.
• Policy templates / copy-from-other-project — beyond bulk-apply-to- descendants. If needed, would slot into the admin page as a "Vorlage anwenden" affordance. Not v1.
• Per-event_type policies — "deadline.create with event_type='Klage' needs partner; everything else of_counsel". The existing schema is per-(entity_type, lifecycle_event); event-type granularity would require an extra column + index. No signal yet.

---

END OF DESIGN.

Inventor stays parked. Awaits m's go/no-go on the 12 locked decisions before any coder shift. Hand-off via head once green.