Twins

Persona twins are a program capability, not a fifth product. Names are fixed in PRODUCT-CONTRACT.md section 11.4 and recorded as built in 11.7; the design is PRODUCT-PLAN.md Part 7. Every item carries the release it belongs to: R3 twins for program personas, R5 stage gates, R6 organisation twins (contract 12.7 and ADR 0032; the R4 release is the workbench, on its own pages).

The R3 items are built in the repositories and every R3 item still carries the status word designed until the release: twins move to preview only when the R3 gates pass (contract 11.1 and Part 7 section 9), and this page changes its chips in the same commit as forge.config.json, the contract and CLAIMS-REGISTER.md. Pins verified in source on 2026-09-15: 87 permissions (EXPECTED_PERMISSION_COUNT), persona version 3 (PERSONA_VERSION), 189 routes in api/scripts/designed-routes.json (EXPECTED_ROUTE_COUNT re-pins to 189 in the same change), migrations 0004_chain and 0005_twins (HEAD = "0005", 60 tables), tone map 61. R5 and R6 items are designed in the older sense: nothing of them exists in code yet, and their numbers are targets.

Renumbered on 2026-09-16 by ADR 0032 and contract 12.7: contract 11.4 placed stage gates in R4 as 0006_stage_gates (tables -> 62, routes 189 -> 196, tone map 62, keys +4 -> 91, persona version 4). Section 12 supersedes those lines: R4 is the workbench release (0006_workbench, tables -> 63, routes -> 206, no new permission key, persona version 3), stage gates ship in R5 as 0008_stage_gates after 0007_lenses, and organisation twins move to R6. Every release label and count on this page carries the section 12 numbering; contract 11.4 keeps the original lines as history. The roadmap and the statuses page carry the same numbers. Phase 4 also fixes the wording of every proposal footer: “Proposed by <Name>’s twin (agent, working as <workbench role>); decided by <Name>” (workbench roles), and the decline reason is entered inline in the item, not in a separate dialog.

Tables

Table counts: 53 after 0003_public; 54 after 0004_chain (audit_chain, table only, because R2 had not shipped when R3 started); 60 after 0005_twins (the six R3 tables). test_migrations.py pins HEAD = "0005" and EXPECTED_TABLE_COUNT = 60, alembic check is clean, and the round trip head -> 0003 -> 0001 -> head -> base -> head is green. R4 adds the three workbench tables as 0006_workbench (63); R5 adds 0007_lenses (65) and the two stage-gate tables as 0008_stage_gates (67); R6 adds 0009_user_grants (68). Part 7 quotes 57 and 59 because it counts without the three public tables and before the chain table.

Columns added by 0005_twins: agent_runs + twin_id, trigger_id, initiated_by, priority (0 for a user-requested run, 10 for a twin), target_id, with a partial unique index on (trigger_id, target_id) while queued or running; run_interrupts + detached; tool_calls + basis_hash; notifications + deliver_after; messages + mentions; audit_events + batch_id, twin_id, trigger_id, delegated_from_user_id with a CHECK that the last is null whenever signature_id is set (the four are left out of the row hash while null, so rows written before R3 keep verifying); users.settings + quiet_hours, digest_time, timezone, inbox_shortcuts, illustrative; programs.settings + twin_defaults (max_open_items, decline_rate_threshold, citation_coverage_min), escalation_days. threads.schedule was migrated then dropped: each phase-2 schedule became a twin paused with paused_reason = migrated, the persona resolved from the owner’s program roles including groups (lead, then scientist, quality reviewer, manufacturing specialist; owner-only rows map to program_owner), the schedule stored as a disabled trigger with no standing plan, a system twin.create audit row and an information inbox item “A schedule from phase 2 was moved to your twin; review it and resume”. Nothing runs until the person approves a standing plan and resumes. R5: programs.settings + gate_critical_milestone_tag.

Permission keys

Grammar product.resource.action, closed verbs, appended after program.agent_memory.manage in catalogue order. Counts: 87 at R3 and at R4 (in code; R4 adds no permission key, contract 12.6), 93 at R5 (the four stage-gate keys below plus org.role_memory.read | manage), one more at R6 (org.twins.use).

Group counts at R3: org 13, program 27, evidence 13, plans 14, review 10, progress 10; sync line permissions in sync: 87 strings (13 org, 74 program) across 2 catalogs; unchanged at R4. R5: review 11, progress 13, org 15 (93 strings (15 org, 78 program)); R6 org 16. No dormant key is created: org.twins.use ships with its routes in R6. program.settings.update is re-described in R5 as “Update program settings” because the gate becomes the only writer of the stage. The full catalog is on the permissions page.

Personas per version

TWIN_OVERSIGHT (program.twins.read) is subtracted from scientist, manufacturing specialist and viewer the way THREAD_OVERSIGHT is; TWIN_PARTICIPANT (program.twins.read_own, program.twins.use, program.handoffs.manage) is added to every program persona but the viewer; program.handoffs.read is absorbed by the program-scope reads; SCIENTIST_APPROVALS_WITHDRAWN names the two approve keys. Organisation personas are unchanged until R6 (org_owner and org_admin + 1; R5 adds org.role_memory.read | manage to the organisation personas, contract 12.6). The sizes are asserted in docs/lib/content.ts (PERSONA_BUNDLE_SIZES) against the copied bundles, and the personas page renders the matrix.

Kinds

Every enumeration is a text column with a named CHECK, as everywhere else (statuses).

Interrupts: detached, bound and batched

• Detached (run_interrupts.detached = true): the interrupt is inserted with its tool_calls rows (proposed, proposal_hash, basis_hash) without touching run.status; the container receives an acknowledgement and continues, and a twin_cycle ends succeeded after filing everything it has. Approval later executes the write server-side from the stored arguments through app/tools/handlers.py under the resolver’s principal; the agent audit row carries interrupt_id, approved_by_user_id, both hashes, twin_id and trigger_id. Expiry writes nothing, marks the item “Expired, nothing written” and leaves the run succeeded; expire_pending fails only attached runs. Console turns stay attached and behave as before.
• Bound-user rule: for any interrupt on a run with twin_id, the twin is checked before the thread rule. write_approval and batch_approval are resolvable by the bound person or an active delegate who holds the item’s write permission; plan_approval by the bound person only; everyone else, including holders of program.threads.read and program.threads.use, gets 403 bound_user_only naming the twin. A standing-plan approval records permission_exercised = program.twins.use.
• Stale proposals: every propose_* tool computes basis_hash over {target_type, target_id, updated_at, status} of the linked record; at approval the service recomputes it and refuses a mismatch with 409 stale_proposal naming the changed fields; the card reads “Changed since proposed”; the proposal stays proposed and nothing is written.
• Batches (batch_approval): one interrupt bundles up to 10 write proposals of the same tool and target type under one batch_key; one open batch per run. InterruptResolve.items[] (1 to 10) is required for a batch and refused (422) otherwise; a top-level decision on a batch is refused. The service mints one batch_id per call and, for each item in its own savepoint, checks the resolver holds that item’s ToolSpec.permission (403 batch_item_forbidden, item failed), verifies basis_hash, requires a reason on decline, applies edits, recomputes approved_hash, executes the write (detached) or records the decision for resume (attached), and writes one interrupt.resolve audit row per item with interrupt_id and batch_id. Approved items are written on the call that approves them; undecided items stay proposed until expiry, when they are marked expired one by one and the interrupt closes with resolution.partial = true and the counts on the card (“5 approved and written, 5 expired”). The response is InterruptResolveResult {batch_id, items[{tool_call_id, status, code?}]}.

Tools

All pass the forbidden-verb test of the catalogue (FORBIDDEN_TOOL_VERBS: approve, request_approval, sign, signature, notify, send_mail); every propose_* handler computes basis_hash.

Seeded capabilities (R3): console.twin_literature_watch, console.twin_handoff, review.twin_check_triage, each with a context of use, limitations and a risk class.

Worker jobs, triggers and registries

TRIGGERABLE_ACTIONS (closed, api/app/db/models/twin.py): connector_object.update, hypothesis.decision, sop_version.update, milestone.update, handoff.accept, experiment.update, approval.create. PAUSE_ACTIONS: role_assignment.delete, user.deactivate. AUDIT_ACTIONS (api/app/services/audit_actions.py) registers every action name write_audit accepts and refuses an unregistered name under test; the post-flush hook runs only for TRIGGERABLE_ACTIONS and PAUSE_ACTIONS, inside a savepoint so a hook failure never fails the record write, never re-enters, coalesces per trigger and interval, and inserts twin_cycle runs with on_conflict_do_nothing on (trigger_id, target_id). New audited mutations: inbox.snooze, inbox.dismiss, inbox.feedback, twin.create, twin.update, twin.pause, twin.resume, twin.retire, twin.duty_enable, twin.duty_disable, twin.self_pause, twin.enqueue, handoff.send, handoff.accept, handoff.decline, handoff.complete, handoff.withdraw, delegation.create, delegation.renew, delegation.expire, delegation.revoke, mention.create; R5 stage_gate.open, stage_gate.ready, stage_gate.reopen, stage_gate.review, stage_gate.close, stage_gate.supersede.

Routes

P is /programs/{program_id}. Counts: 157 after the site wave, 189 at R3 (+32, listed in api/scripts/designed-routes.json), 206 at R4 (+17, the workbench routes of contract 12.7), 223 at R5 (+17: stage gates 7, lens reviews 3, role memory 6, propose-share 1), 228 at R6 (+5, the two organisation-twin routes among them). Router order: inbox after me_settings; twins, handoffs, board, metrics after progress; the export in audit_export. make routes-check prints check_routes: 189 designed, 0 missing once the R3 routers are mounted.

Error codes added: R3 stale_proposal, handoff_exists, self_handoff, twin_paused, twin_active_exists, duty_unavailable, delegation_invalid, batch_item_forbidden, bound_user_only, baseline_missing; R5 gate_incomplete, gate_stage_restricted, reviewer_role_required, same_signer, stage_via_gate. Every route is listed with its rule on the API page.

Fixed phrases

Console copy (web/lib/content.ts consoleCopy, mirrored by docs/lib/content.ts), quoted by the web app, the docs and the deck and never paraphrased; angle-bracket parts are filled at render time.

Twin run footers read “Started by schedule, event, hand-off or you under Name’s standing plan (approved date, plan hash prefix)” and never “Requested by”. The word is “agent-generated”; nothing is described as generated by a model or a vendor. Inbox groups in display order: Signatures, Approvals, Questions, Hand-offs, Mentions, Information. Board columns: “Waiting on scientists”, “Waiting on QA”, “Waiting on the lead”, “Waiting on the owner”, “Waiting on manufacturing”. Console routes: /me/inbox, /me/inbox/[itemId], /me/brief, /me/delegations, /p/[slug]/board, /p/[slug]/twin, /p/[slug]/handoffs/[id].

Source: PRODUCT-CONTRACT.md sections 11.4 and 11.7; PRODUCT-PLAN.md Part 7 sections 5, 6 and 7 (7.1 to 7.5); api/app/auth/permissions.py (EXPECTED_PERMISSION_COUNT = 87); api/app/auth/personas.py (PERSONA_VERSION = 3); api/scripts/designed-routes.json (189); api/alembic/versions/0004_chain.py; api/alembic/versions/0005_twins.py; api/tests/test_migrations.py (HEAD = "0005", EXPECTED_TABLE_COUNT = 60); api/app/db/models/twin.py; api/app/db/models/inbox.py; api/app/db/models/handoff.py; api/app/db/models/delegation.py; api/app/db/models/agent.py; api/app/db/models/conversation.py; api/app/services/audit_actions.py; api/app/services/interrupts.py; api/app/services/notifications.py (EMAILED_KINDS); api/app/tools/catalogue.py (FORBIDDEN_TOOL_VERBS); api/app/db/models/signatures.py; api/app/db/models/progress.py; web/lib/api/types.ts; web/lib/content.ts; web/lib/status.ts (TONE_STATUS_COUNT = 61); docs/lib/content.ts