Mariano/cs 437

[Marfuen]

What does this PR do?

• Fixes #XXXX (GitHub issue number)
• Fixes COMP-XXXX (Linear issue number - should be visible at the bottom of the GitHub issue description)

Visual Demo (For contributors especially)

A visual demonstration is strongly recommended, for both the original and new change (video / image - any one).

Video Demo (if applicable):

• Show screen recordings of the issue or feature.
• Demonstrate how to reproduce the issue, the behavior before and after the change.

Image Demo (if applicable):

• Add side-by-side screenshots of the original and updated change.
• Highlight any significant change(s).

Mandatory Tasks (DO NOT REMOVE)

• I have self-reviewed the code (A decent size PR without self-review might be rejected).
• I have updated the developer docs in /docs if this PR makes changes that would require a documentation change. If N/A, write N/A here and check the checkbox.
• I confirm automated tests are in place that prove my fix is effective or that my feature works.

How should this be tested?

• Are there environment variables that should be set?
• What are the minimal test data to have?
• What is expected (happy path) to have (input and output)?
• Any other important info that could help to test that PR

Checklist

• I haven't read the contributing guide
• My code doesn't follow the style guidelines of this project
• I haven't commented my code, particularly in hard-to-understand areas
• I haven't checked if my changes generate no new warnings

---

Summary by cubic

Adds the ISO 27001 ISMS area with six auto-derived, editable, versioned documents (4.1, 4.2a, 4.2b/c, 4.3, 5.1, 6.2) plus DOCX/PDF export, approvals, drift detection, and a short setup wizard. Delivers CS-437 by letting customers generate auditor-ready foundational documents from existing platform data.

• New Features

  • “ISO 27001 (ISMS)” tab on Documents (shown when ISO 27001 is active and is-isms-enabled is on) with cards for Context (4.1), Interested Parties (4.2a), Requirements & Treatment (4.2b/c), Scope (4.3), Leadership (5.1), Objectives (6.2); full detail pages with registers or narrative forms.
  • Deterministic generation from org data with drift alerts; manual edits preserved; one-click regenerate; branded DOCX/PDF exports via docx and jspdf-autotable.
  • Submit/approve/decline workflow with version snapshots; document↔control links at org level; Framework Editor “ISMS Documents” mapping each doc to a clause requirement and control templates; ensure-setup is template-driven and idempotent.
  • Generic register endpoints for issues/parties/requirements/objectives; a ~12‑question wizard stores an ISMS profile and can generate all six documents; routes/pages are gated for private testing.

• Bug Fixes

  • Approvals: approve/decline require needs_review and the assigned approver; any content edit (registers, narrative, control links) reverts approved docs to draft; control-link edits only downgrade approval when links actually change; approval runs with snapshot capture in one transaction.
  • Drift/determinism: detects wizard/vendor-category/department/member changes and Interested Parties edits via a stable fingerprint; deterministic selections; regulator dedupe; blank objectives ignored; Scope/Leadership include wizard answers.
  • Data integrity and UX: requirement party IDs validated to the same document; objectives owner validated; ensure-setup derives org from session; Zod-validated bodies documented via @ApiBody; narrative save is atomic and preserves user content unless empty; single isLatest version enforced; register creates serialize position allocation with a per-document advisory lock; stable forms and export uses apiClient.

^{Written for commit e92d083. Summary will update on new commits.}

[linear]

CS-437

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
comp-framework-editor	Ready	Preview, Comment	Jun 3, 2026 9:19pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
app	Skipped		Jun 3, 2026 9:19pm
portal	Skipped		Jun 3, 2026 9:19pm

[Marfuen]

@cubic-dev-ai ultrareview this

[Marfuen]

@cubic-dev-ai review this

[cubic-dev-ai]

@cubic-dev-ai review this

@Marfuen I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

cubic analysis

10 issues found across 203 files

Confidence score: 2/5

• There is a concrete user-impacting regression risk in apps/app/src/app/(app)/[orgId]/documents/isms/components/ContextOfOrganizationClient.tsx: handleUpdateIssue swallows API errors, so IssueRow can exit edit mode and lose unsaved edits when save fails.
• Several high-confidence behavior issues (7/10) increase merge risk, including stale local state in apps/framework-editor/app/(pages)/isms-documents/useIsmsDocumentRows.ts after template re-fetches and hardcoded admin-only access in apps/api/src/framework-editor/isms-document-template/isms-document-template.controller.ts that can block RBAC-based delegation.
• Data-intent consistency is also at risk in apps/api/src/isms/documents/objectives.ts and apps/api/src/isms/documents/org-profile.ts, where explicitly saved empty values can be overwritten by regenerated defaults.
• Pay close attention to apps/app/src/app/(app)/[orgId]/documents/isms/components/ContextOfOrganizationClient.tsx, apps/framework-editor/app/(pages)/isms-documents/useIsmsDocumentRows.ts, apps/api/src/framework-editor/isms-document-template/isms-document-template.controller.ts, apps/api/src/isms/documents/objectives.ts, and apps/api/src/isms/documents/org-profile.ts - these carry the highest chance of user-visible regressions and authorization/data-intent mismatches.

Linked issue analysis

Linked issue: CS-437: [Feature] A. Foundational documents

Status	Acceptance criteria	Notes
✅	Add an ISMS area in Documents (ISO 27001 / ISMS tab) and an ISMS overview with document cards	Front-end tab wiring and overview components added; DocumentsPageTabs updated and IsmsOverview plus many UI cards/components added.
✅	Provide the six foundational document types (4.1 Context, 4.2a Interested Parties, 4.2b/c Requirements, 4.3 Scope, 5.1 Leadership Commitment, 6.2 Objectives)	Schema, type definitions and handler modules for each document type are present; ISMS_TYPE_DEFINITIONS and IsmsDocumentType defined; per-document derivation modules added.
✅	Deterministic generation from platform data (collectPlatformData + per-document derivations) and generate-all flow	Platform-data collection, generate/runDerivation and replace-derived-rows logic implemented; generate-all DTO and service paths exist.
✅	Customer-editable registers where manual overrides are preserved (derived → manual on edit) and regenerate preserves manual edits	Services flip derived rows to 'manual' on edit and replaceDerivedRows preserves manual rows; register services and controllers added for CRUD.
✅	Versioning, submit/approve/decline workflow and approval invalidation when content changes	IsmsDocument and IsmsDocumentVersion model work is supported by services and DTOs; approval invalidation helper and narrative save that resets approvals implemented; submit/approval DTO and UI present.
✅	Export to DOCX and PDF (branded, cover metadata, structured sections)	Both docx and PDF renderers implemented, export generator dispatch, DTO and client export helper present; deps added to package.json.
✅	Short setup wizard (~12 questions) that persists profile answers and can generate all documents in a single session	Full wizard client + server-side profile schema, services and generate-all plumbing implemented, including defaults and merge logic.
✅	Drift detection and one-click regenerate UI (flagging when underlying platform data changed)	Snapshot diffing and snapshot upsert implemented; drift API/hooks and UI components exist (useIsmsDrift, DriftBanner, snapshot logic).
✅	Consolidated register CRUD endpoints (create / update / delete) routed by register segment	A generic register-registry routes requests to per-register services; controller exists exposing create/update/delete for registers.
⚠️	Definition-of-done: Pressmaster and Kidan packs reproducible and match/exceed hand-authored quality	Renderers and metadata exist to create DOCX/PDF outputs and a QA file was added, but there is no example output or explicit automated regression comparing generated packs to existing hand-authored artifacts in the diff to verify parity/quality.
⚠️	Definition-of-done: Pressmaster/Kidan Stage-1 findings (4.1,4.2,4.3,6.2) closable using platform output alone	Generation targets the specified clauses and derivation logic maps platform data to clause content, but auditor acceptance is outcome-level and there are no audit-run artifacts or acceptance tests proving those engagements' findings are closable solely with generated docs.

<sub>Tip: instead of fixing issues one by one fix them all with cubic
Partial review: This PR has more than 100 files, so cubic reviewed the highest-priority files first.
For a deeper review of large PRs, comment @cubic-dev-ai ultrareview. Learn more.

Re-trigger cubic</sub>

[Marfuen]

@cubic-dev-ai review this

[cubic-dev-ai]

@cubic-dev-ai review this

@Marfuen I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

cubic analysis

11 issues found across 207 files

Confidence score: 3/5

• There is concrete regression risk in persistence logic: packages/db/prisma/migrations/20260529172752_add_isms_foundational_documents/migration.sql allows multiple isLatest=true rows, which can make “latest version” reads nondeterministic.
• apps/api/src/isms/isms-narrative.service.ts and apps/api/src/isms/isms-context-issue.service.ts perform key reads/calculations outside transactions, creating race windows under concurrency (wrong-version narrative writes, unique-constraint crashes, and duplicate ordering positions).
• Workflow integrity is also at risk: apps/api/src/isms/isms-document-control.service.ts can modify approved documents without triggering approval invalidation, and several frontend schema/linking issues increase validation and data-consistency drift risk.
• Pay close attention to packages/db/prisma/migrations/20260529172752_add_isms_foundational_documents/migration.sql, apps/api/src/isms/isms-narrative.service.ts, apps/api/src/isms/isms-context-issue.service.ts, apps/api/src/isms/isms-document-control.service.ts - they carry the highest likelihood of user-visible data integrity and process-state regressions.

Linked issue analysis

Linked issue: CS-437: [Feature] A. Foundational documents

Status	Acceptance criteria	Notes
✅	Add new ISO 27001 (ISMS) Documents area and navigation tab (feature-flagged / framework-gated)	Frontend adds ISMS overview/route, DocumentsPageTabs was updated to surface an ISMS tab and layout enforces feature-flag + framework gating.
✅	Implement the six foundational document types server-side (types, DB schema, migrations, templates)	Prisma schema, multiple migrations and template seed entries add the IsmsDocument types and related tables.
✅	Deterministic generation of document content from platform data (collect + per-document derivations)	There is a centralized data collector and per-document derivation modules with unit tests; runDerivation wires them into generation logic.
✅	Documents are editable and manual overrides are preserved (editing flips source to manual)	Register services explicitly flip derived rows to 'manual' on edit; narrative save and register CRUD exist; UI provides inline edit forms.
✅	Versioning and approval workflow (submit / approve / decline) with approval invalidation on edits	Document version snapshot upsert, approval DTOs and narrative/version services exist; invalidateApprovalIfNeeded used when edits occur.
✅	DOCX and PDF export (branded) implemented	Export generator + separate DOCX and PDF renderers exist, with metadata handling including primary colour; docx/jspdf deps added.
✅	Setup wizard to collect non-derivable inputs and ability to generate all six documents	Wizard schema, controller/service, client components, generate-all DTO and generate flow are implemented and tested; defaults and merging logic present.
✅	Frontend: overview, per-document detail pages and register UIs (add/update/delete)	Many client components implement overview cards, per-document shells, register tables, add/edit rows, control mapping, and tests are included.
✅	Drift detection and one-click regenerate flow (snapshot, diff, UI banner)	Snapshot capture, diff logic and UI drift banner plus useIsmsDrift hook and regenerate flows are implemented.
✅	Control ↔ ISMS document mapping (link/unlink controls)	Backend control-link service and frontend control-mapping UI and APIs are implemented.
⚠️	Exports & generation in a single session (wizard → generate → export all six documents)	All pieces exist (wizard, generateAll, export endpoints and client hooks), showing an end-to-end path. However, end-to-end integration tests or an explicit e2e flow demonstrating export-of-all-six-in-single-session are not present in the diff to fully validate this behavior in CI.
❌	Pressmaster and Kidan packs are reproducible and platform output alone closes Stage-1 findings	The issue's DoD requires reproducing specific vendor packs and closing real audit findings; the PR implements the generation pipeline and export tooling, but I see no explicit seeded content, acceptance tests, or sample outputs demonstrating Pressmaster/Kidan comparability or any audit-closing validation artifacts in this diff.

<sub>Tip: instead of fixing issues one by one fix them all with cubic
Partial review: This PR has more than 100 files, so cubic reviewed the highest-priority files first.
For a deeper review of large PRs, comment @cubic-dev-ai ultrareview. Learn more.

Re-trigger cubic</sub>

[cubic-dev-ai]

4 issues found across 23 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>