Required Policies

Partially implemented. The all and list selectors with seed-and-enforce are live end-to-end (policy CRUD, every-minute reconcile cron, label stamping, admin page). Two declared options are not yet effective: the tagged selector matches zero projects (the projects table has no tags column yet), and seed-only policies are skipped by the reconciler - nothing provisions them automatically today.

Required workflow policies let operators guarantee that specific workflow templates are installed on every project that matches a selector. This is the governance layer that ensures compliance templates, SDLC defaults, and security-gate workflows are present even when projects are created long after the policy was written.

Policy concepts

A required_workflow_policy has three key fields:

Field	Description
`templateSlug`	The workflow template to install (e.g. `sdlc-v2`, `bfsi-approval-gate`)
`templateVersion`	Optional semver pin; omitted means the template's latest published version
`enforcement`	`seed-and-enforce` - the reconciler auto-installs now and on new matching projects; `seed-only` - declarative record only, not yet provisioned by any automated path (the reconciler skips it)
`appliesTo`	Project selector: `all` (every project), `tagged` (projects matching `projectTagSelector.tags` - not yet effective, see below), or `list` (explicit `projectIdList`)

Enforcement modes

`seed-and-enforce`

The reconciler actively ensures the template is installed on every matching project. If a project was created after the policy was written, or if the template was deleted, the reconciler re-installs it.

Use this for:

Mandatory compliance templates (BFSI gates, audit workflows)
Organisation-wide SDLC standards

`seed-only`

Declares that a template should be seeded once without recurring enforcement - but no automated path provisions seed-only policies today. The reconciler explicitly skips them (action: 'skipped', reason: 'seed-only'), and no other code path installs them. Until seeding ships, a seed-only policy is a declarative record only; install the template manually if you need it on a project now.

Intended for (once seeding ships):

Default starter templates that teams should customise freely
Onboarding helpers that are suggestions, not mandates

The reconciler

The reconciler runs in two contexts:

Cron job - GET /api/cron/required-workflows fires every minute (Vercel Cron)
Operator CLI - scripts/reconcile-required-workflows.ts --apply for immediate ad-hoc runs

For each seed-and-enforce policy, the reconciler:

Resolves the matching project set per the appliesTo selector - all and list resolve normally; tagged currently resolves to an empty set (no project-tags schema yet), so tagged policies reconcile as a no-op
For each non-archived project, checks whether the template is already installed
If not installed → installs it and stamps the label rensei.required-policy-id: {policyId} on every created workflow row
If already installed but missing the label → stamps the label idempotently

Dry-run mode (default) returns a ReconcileResult describing what would happen without writing anything. Pass --apply to execute.

Project actions per reconcile run

type ProjectAction =
  | { projectId: string; action: 'install'; templateSlug: string; version: string }
  | { projectId: string; action: 'stamp-label'; workflowIds: string[]; templateSlug: string }
  | { projectId: string; action: 'already-ok'; templateSlug: string }
  | { projectId: string; action: 'skipped'; reason: 'project-archived' | 'template-missing' | 'version-missing' | 'seed-only'; templateSlug: string }

Label stamp

Workflows installed by the reconciler are stamped with:

metadata:
  labels:
    rensei.required-policy-id: pol_abc123

This label ties the workflow back to the policy that governs it. The admin UI shows this badge on managed workflows. Operators can query for all managed workflows by filtering on this label.

Admin API

Policy CRUD is operator-only (platform operator session - not org API keys). The reconcile cron authenticates with the deployment's cron secret.

GET /api/admin/required-workflow-policies?orgSlug=acme
# Requires an operator session

POST /api/admin/required-workflow-policies
Content-Type: application/json
# Requires an operator session

{
  "orgId": "org_abc123",
  "templateSlug": "bfsi-approval-gate",
  "enforcement": "seed-and-enforce",
  "appliesTo": "list",
  "projectIdList": ["proj_regulated_1", "proj_regulated_2"]
}

For appliesTo: "all" omit both selector fields; for appliesTo: "tagged" pass projectTagSelector: { "tags": ["bfsi-regulated"] } (accepted and stored, but matches zero projects until the project-tags schema ships).

POST /api/cron/required-workflows
Authorization: Bearer $CRON_SECRET   # or x-api-key for external schedulers

Manually triggers the reconciler. Vercel Cron calls the GET form of this endpoint every minute.

Skipped projects

The reconciler silently skips a project when:

project.deletedAt IS NOT NULL - project is archived
The template's latestVersion is NULL - template has never been published
The pinned version no longer exists in the DB - version was deleted
The policy is seed-only - the reconciler never installs for seed-only policies

Skipped actions are included in the ReconcileResult.projectActions array with action: 'skipped' and a reason code.

Idempotency

The reconciler is fully idempotent. Running it multiple times against the same set of projects produces the same outcome. Template installs use installTemplateForProject which is also idempotent - re-installing an already-installed template is a no-op.

Operator admin page

Navigate to Admin → Required Workflow Policies to:

View all active policies and their selectors
See which projects each policy covers
Inspect recent reconcile outcomes
Create, edit, or delete policies

Publish and Deploy - workflow lifecycle states
SDLC Template Subscriptions - per-project subscription model
Compliance: BFSI Overview - governance-driven template enforcement

On this page