Support inspector signatures on agreements

Objective

• Support inspector signatures on inspection agreements for markets (e.g. Washington, Oregon) where both the client and the inspector must sign before the inspection proceeds.
• Eliminate manual workarounds while preserving the correct inspector identity on the signed agreement record.
• Keep the existing client signing flow intact; add a complementary inspector signing capability.

Background

• During an implementation call, the team discussed Washington law requiring both client and inspector signatures on the inspection agreement; Oregon was mentioned as a similar market.
• The open product question is how and when the inspector signature should be applied. Ideas discussed included:
• Storing an inspector signature on the inspector profile
• Stamping the agreement when the report is published or when the job starts
• Allowing the assigned inspector to sign directly on the job before the inspection begins
• Edge cases called out for clear handling:
• Inspector reassignment before the inspection
• Multiple inspectors on a job
• Someone other than the inspector publishing the report
• Signature timing must still satisfy pre-inspection compliance requirements
• Current behavior (code audit): Attik agreements today support client/contact signing only. The client portal flow in AgreementSigningSection.tsx / AgreementSigningForm.tsx collects one signature and submits via agreements.ts PATCH with status: 'signed'. Signing requires a portal-access token with contactId and a contact role granting agreement permission. The agreementSchema stores a single signer (signedBy, signedByEmail, signatureData, signedRenderedHtml, etc.) — no inspector signature fields. Agreement templates support text and initials blocks (AgreementBuilderBase.tsx, initialsBlock in merged content); there is no inspector signature block type. Report unlock treats agreements as signed when the client has signed all active non-stale agreements (computeAgreementSignedForReportLock.ts, agreementLockSync.ts, checkReportAccess.ts). Inspector signatures on Spectora reports (InspectorSignatureSection.tsx) are a separate path from report/Spectora data and do not satisfy agreement signing requirements. The Attik inspectorSchema has no stored signature field for agreements today.

Decisions needed (product)

Lock before or during implementation:

1. When inspector signature is captured — profile stamp vs job-level sign before inspection vs tied to report publish/job start (only options that meet pre-inspection compliance are valid for WA/OR).
2. Where the inspector signs — Tools inspection/workorder UI, mobile app, or automated stamp from profile.
3. Which inspector when multiple are assigned — primary only, all assigned, or configurable per company.
4. Reassignment behavior — invalidate/require re-sign, or keep original inspector signature.
5. Report lock — whether inspector signature is required for agreement.signed / report access, or tracked separately from client sign.
6. Company/market enablement — global feature vs per-company or per-state setting.

Scope

Backend

• Extend agreement signing data model beyond single client signature — e.g. inspector identity, timestamp, signature image/data, and rendered output — in or alongside agreementSchema.ts.
• New or extended routes in agreements.ts (or inspector-specific signing endpoint) with auth appropriate for inspector/staff (not client portal contactId flow).
• Agreement merge/render pipeline (mergeAgreementBlocksToContent.js, renderAgreementDocToHtml.ts, signedRenderedHtml capture) must include inspector signature in the immutable signed record when applicable.
• Decision needed: whether inspector signature invalidates or triggers stale agreement logic (agreementStaleWorker.ts, signedContentHash / computeSignedContentHash).
• Decision needed: updates to agreementLockSync.ts / checkReportAccess.ts if inspector sign is required for compliance before reports unlock.
• Inspector profile storage (if profile-based approach chosen) would touch inspectorSchema.ts and inspector settings routes — not present today.

Frontend — Client portal

• Agreement view/sign pages under src/app/client/job/[slug]/agreement/[id]/ — today client-only. May need read-only display of inspector signature once applied, or dual-signer UX if inspector signs via portal (unlikely; decision needed).
• AgreementContent.tsx / template builder may need a new block type or merge-field for inspector signature placement in PDF/HTML output.

Frontend — Tools

• Inspector signing entry point on inspection/workorder (src/app/tools/inspections/[id]/) or agreements UI — not built today.
• Agreement template builder (src/app/tools/agreements/templates/[id]/, AgreementGlobalBlockModal.tsx) — extend block types beyond text and initials if inspector signature appears in template body.
• Settings if profile-stored signature: inspector settings under src/app/tools/settings/inspectors/.

Mobile

• Decision needed: whether inspectors must sign from attik-mobile in v1 or Tools web only.

Explicitly out of scope unless product expands

• Using report publish inspector signatures (InspectorSignatureSection.tsx) as a substitute for agreement compliance without explicit product approval
• Replacing client signing flow or contact-role agreement permission model

Acceptance themes (from edge cases)

• Correct inspector identity on the final agreement artifact after reassignment scenarios are resolved per product decision.
• Multi-inspector jobs handled consistently (not silently wrong signer).
• Pre-inspection timing: agreement with inspector signature satisfies compliance before inspection start, independent of who publishes the report.

References

• Client agreement signing: attik-frontend/src/app/client/job/[slug]/agreement/[id]/components/AgreementSigningSection.tsx, AgreementSigningForm.tsx
• Agreement API & sign gate: attik-backend/src/routes/agreements.ts
• Agreement model: attik-backend/src/models/agreementSchema.ts
• Template blocks: attik-frontend/src/app/tools/agreements/templates/[id]/AgreementBuilderBase.tsx
• Report lock / agreement signed: attik-backend/src/util/functions/agreements/agreementLockSync.ts, attik-frontend/src/util/functions/report/computeAgreementSignedForReportLock.ts
• Report inspector signature (separate system): attik-frontend/src/app/client/reports/components/InspectorSignatureSection.tsx