Handbook
Changes to the v1 enterprise-uplift plan
Use the existing prompts, with these inserted gates:
Updated
Revised sequence
Use the existing prompts, with these inserted gates:
00 Repository discovery
01 Dual wiki
02 IA, RBAC, data visibility, and technical plan
02A Cryptography and trust-boundary gate NEW, blocking
03 Design system and application shells
03A Responsive shell and state-evidence baseline NEW, merge with 03 if preferred
06 Auth, invite, onboarding, and account security
07 Individual workspace and survey productization
08 Manager workspace
09 HR workspace
10 Tenant admin
11 Global admin
12A Existing AFF domain audit NEW, before 12
12 Question library, packs, and program builder
13 Campaign and rater lifecycle
14A Results scoring and rendering safety NEW, before or inside 14
14 Results, analytics, and reporting
15 PDP and adaptive follow-up
16 Integrations, billing, and entitlements
17 Hardening
18A Static export and screenshot contract NEW, start early and re-run at release
18 Migration and release readiness
Marketing and documentation shells may be implemented after Prompt 03, but privacy, security, and capability claims must remain blocked until Prompt 02A has an approved outcome.
Prompt 00 changes
Add explicit discovery of:
- all uses of
private_key_b64 - whether private keys reach application servers, workers, logs, telemetry, or query strings
- the lifecycle of
consented_scores - server-side aggregation and deletion behavior
- the actual AFF domain, migrations, schedulers, ledger, selection engine, and tests
- report rendering through
iframe.srcdoc - support-mode tenant impersonation or delegation
- static-export generation and asset path rewriting
- screenshot/capture scripts and state assertions
Do not classify the system as zero-knowledge based on UI copy.
Prompt 02 changes
Prompt 02 remains valid, but its encryption ADR becomes blocking rather than advisory. It must hand off to Prompt 02A before implementation.
The role model should be capability-first. The supplied fixture shows that "tenant admin" can manage directory and view completion while not having survey-management capability. Avoid assuming a job title grants a fixed bundle.
Prompt 03 changes
The code already uses Forge theme and shell CSS. Prompt 03 should inventory and rationalize these assets rather than create a parallel design system.
Add acceptance criteria for:
- a compact mobile top bar
- sidebar-to-drawer behavior
- mobile table alternatives or safe horizontal scrolling
- sticky survey composer and visible progress
- no page where navigation consumes most of the first mobile viewport
- visual tests at 390, 768, 1024, and 1280 px
Prompt 04 and 05 changes
Add a content truth gate:
- No zero-knowledge or "server cannot read" claim without Prompt 02A evidence.
- Document the exact readable and encrypted data classes.
- Explain recovery and key custody without implying stronger guarantees.
- Mark external Thomas imports and native Capablio evidence separately.
Prompt 06 changes
Preserve the current key/envelope concepts only after the trust model is approved.
Add requirements for:
- no private key in request bodies, query strings, logs, telemetry, or support tooling for a subject-private mode
- device-bound or otherwise approved key storage
- clear recovery mode selection
- no requirement to import a private key before identity validation unless explicitly approved
- safe migration from current key files
- CSP and third-party script review because key material is currently accessible to same-origin JavaScript
Prompt 07 changes
Treat the conversational survey as an existing vertical slice.
Preserve and improve:
- assignment selection
- progress/resume
- statement, open-text, importance, and Not observed steps
- rephrase/example assistance
- sealed submission where the approved architecture supports it
Add separate modes:
- short pulse: 1 to 5 items, minimal chrome, immediate completion
- medium recurring survey: sections and save/resume
- deep 360: section navigation, review, estimated time, revisit answers, and completion summary
Do not force a 73-step chat pattern onto daily or weekly AFF programs.
Prompt 09 and 13 changes
The current lifecycle is a real state machine seed, but it permits manual advancement and renders raw proposal JSON plus every email body on one extremely long page.
Add:
- transition readiness checks and reasons
- state-specific permissions
- named rater tables
- progressive disclosure through tabs/drawers
- notification jobs and delivery history
- pagination/virtualization for recipients
- batch reminder and resend controls
- no raw sign-in URLs in ordinary page text
- one-time secret handling where required
- idempotent transitions and send operations
Prompt 12 changes
Run Prompt 12A first. Reuse existing pack and program identifiers where valid.
Prompt 12 should focus on:
- filling verified domain gaps
- tenant overlays and governed versioning
- admin authoring and simulation UI
- coverage/cooldown/PDP invariants
- observability and explainability
Do not fork a second AFF model just because the current UI does not expose the first one.
Prompt 14 changes
Add scoring governance:
- a published campaign references an immutable scoring-policy version
- ordinary subjects cannot alter rater weights
- recomputation is a governed analysis action with provenance, not a casual UI control
- verification diagnostics are separated from the participant report
- every result shows source, policy version, valid N, suppression, and observation period
Replace or strictly sandbox iframe.srcdoc. Prefer native accessible report components. If iframe rendering remains, define sandbox flags, CSP, sanitization, origin behavior, print behavior, and screen-reader acceptance tests.
Prompt 15 changes
Preserve the structured PDP engine and goal lifecycle, but replace JSON/plain-text implementation inputs with real fields.
Keep private and shared content distinct. The PDP API must follow the approved encryption boundary and must not require the browser to transmit a subject private key to the service.
Prompt 17 changes
Add targeted tests for:
- private key exfiltration
- sensitive data in URLs and logs
- plaintext score retention
- iframe report injection
- stored/reflected XSS through people and comment data
- sessionStorage compromise assumptions in the threat model
- mobile navigation and table overflow
- visual-state fixture correctness
Prompt 18 changes
The static export problem has a concrete cause class: exported pages reference assets with incorrect relative locations and reveal hidden panels when CSS does not load.
Do not postpone this entirely to release. Establish the export contract early, then re-run it at release.
Static demos must:
- bundle or rewrite asset paths
- contain only the intended state
- remove bearer-token, private-key, and internal diagnostic controls
- use synthetic data only
- work from the documented serving mode
- pass screenshot assertions and print/PDF checks