@synap-core/workspace-templates 0.9.4 → 0.11.0

package/src/grants.yaml

@@ -43,6 +43,16 @@ dependencies:
     kind: workspace
     relation: require
     reason: "Provides the pod-wide client / partner / sponsor role vocabulary this workspace reuses."
+  # This template REFERENCES the pod-wide `grant-program` kind (the per-chain
+  # funding-program parent) that the blockchain-ecosystem overlay defines. The
+  # 3-layer grants spine is program → round → grant_submission: `round` (owned
+  # here) `belongs_to` a `grant-program` (owned there). `require` installs that
+  # overlay FIRST so `grant-program` exists (pod-wide) before this template
+  # provisions the edge + deadline view — same deps-first pattern as foundation.
+  - slug: blockchain-ecosystem
+    kind: workspace
+    relation: require
+    reason: "Provides the pod-wide grant-program kind (per-chain funding programs) this workspace's rounds belong to."
 
 workspace:
   name: Grants Pipeline
@@ -730,6 +740,14 @@ profiles:
           - healthy
           - at_risk
           - critical
+      - slug: driveLink
+        label: Drive folder
+        valueType: string
+        inputType: url
+      - slug: driveFolderId
+        label: Drive folder ID
+        valueType: string
+        inputType: text
   # ── Partner (shared ecosystem role — SSOT is foundation.yaml) ─────────────
   - slug: partner
     displayName: Partner
@@ -865,11 +883,26 @@ views:
         - averageAwardAmount
       sortBy: roundNumber
       sortDir: desc
+  # Round deadlines on one time axis. Scoped to `round` ONLY: rounds are the
+  # deadline SSOT (they carry `submissionDeadline`); `grant-program` carries
+  # `nextDeadline`, which the calendar's dateField fallback chain
+  # (dueDate/startDate/startTime/date) never resolves, so a program would land
+  # dateless in the "Unscheduled" backlog. Plotting programs + rounds on ONE
+  # timeline is a deferred UI-phase item. `colorField` (NOT `colorBy` — the
+  # calendar adapter reads `colorField`) colors each round by its status.
+  - name: Deadlines
+    type: calendar
+    scopeProfileSlug: round
+    description: Upcoming round submission deadlines, on one time axis.
+    config:
+      dateField: properties.submissionDeadline
+      colorField: status
+  # No `coverField`: grant-project has no image property (`summary` is prose, so it
+  # rendered as a text/blank cover). Fall back to the gallery's clean default cover.
   - name: Awarded Projects
     type: gallery
     scopeProfileSlug: grant-project
     config:
-      coverField: summary
       showFields:
         - currentStatus
         - awardedRoundCount
@@ -899,6 +932,35 @@ entityLinks:
     targetProfileSlug: company
     type: submitted_by
     label: Submitted By
+  # The application belongs to the engagement that pursued it (contract lives in
+  # the composed operations base). Closes the spine on the submission side.
+  - sourceProfileSlug: grant_submission
+    targetProfileSlug: contract
+    type: for_contract
+    label: Engagement
+  # The commercial bridge: a grant application maps to its fee/commission `deal`,
+  # so a grant win is tied to the money. Mirrors networking.yaml's canonical
+  # `intro → billed_as → deal` commercial-mapping predicate (same edge type,
+  # reused for one consistent meaning across the pod graph). `deal` resolves here
+  # because it is a SYSTEM profile (validate.ts `SYSTEM_PROFILES`) — so this needs
+  # NO crm compose (grants stays an operations overlay, not a CRM). The deal lives
+  # in the CRM workspace; this is a cross-workspace relation, consistent with
+  # grant_submission's other cross-domain edges (submitted_by → company).
+  - sourceProfileSlug: grant_submission
+    targetProfileSlug: deal
+    type: billed_as
+    label: Billed as
+  # 3-layer spine: a round is one cycle OF a long-lived program (SCF #42 → SCF).
+  - sourceProfileSlug: round
+    targetProfileSlug: grant-program
+    type: belongs_to
+    label: Program
+  # The engagement pursues a program (contract lives in the composed operations
+  # base; grant-program in the required blockchain-ecosystem overlay).
+  - sourceProfileSlug: contract
+    targetProfileSlug: grant-program
+    type: pursues
+    label: Pursues
   - sourceProfileSlug: grant-project
     targetProfileSlug: round
     type: appears_in
@@ -915,6 +977,199 @@ entityLinks:
     targetProfileSlug: grant_submission
     type: evidenced_by
     label: Evidenced By
+
+# The BASE grant playbook — ONE reusable, data-driven process that runs an
+# engagement through ANY program. Chain-specifics (cadence, submissionTracks,
+# trancheModel, nextDeadline) are READ from the `grantProgram` entity at runtime,
+# NOT hardcoded per chain — so one playbook serves Stellar SCF, Optimism RetroPGF,
+# etc. Only a genuinely different-SHAPED program later earns its own override
+# playbook (base + data-driven-override decision). Generalizes the Stellar staged
+# advisor (CP `stellar-grant-client`) into a template. Bound to `contract` (the
+# engagement, per decision — NOT company); targets a `grant-program` param — the
+# 3-layer spine (contract → grant-program → round → grant_submission) made runnable.
+playbooks:
+  - name: Grant Process
+    description: Run an engagement through a grant program end to end — identify fit, draft the application, submit, track the decision, and deliver the tranches. Reads the program's own cadence / tracks / tranche model so one playbook fits every chain.
+    goalTemplate: >-
+      Advance this engagement ({contract}) through the grant program
+      ({grantProgram}) it is pursuing. FIRST read the program entity's own data —
+      its cadence, submissionTracks, trancheModel, and nextDeadline — plus the
+      client context on the contract, and let THOSE drive the plan: do not assume
+      a chain's mechanics, read them from the program. Then work the stages in
+      order and keep the client's `grant_submission` card as the durable state of
+      record:
+
+      1. Identify — understand the project and which of the program's
+         submissionTracks fit; set the submission `stage` to `scope`.
+      2. Draft — write the abstract, then the full proposal (products & services,
+         success criteria, GTM, traction); move `stage` `abstract` → `build` and
+         fill the submission's body fields.
+      3. Submit — finalize against the program's nextDeadline and submit; once
+         submitted, set `stage` to `awaiting-results`.
+      4. Awaiting — track the decision and keep `status` current
+         (in-review / waiting-client / needs-document / blocked).
+      5. Awarded — on a decision, set `outcome` (awarded / rejected / partial)
+         and record the awarded amount.
+      6. Delivering — for an award, work the program's trancheModel: fill the
+         tranche deliverables and update trancheCompletion as each milestone ships.
+
+      Never fabricate — leave a field blank rather than guess. Every write is
+      proposal-gated for the user to review.
+    subjectProfile:
+      profileSlug: contract
+    params:
+      - { name: contract, type: entity, profileSlug: contract, label: Engagement, required: true }
+      - { name: grantProgram, type: entity, profileSlug: grant-program, label: Grant Program, required: true }
+    # Generic stages, mapped onto grant_submission's own stage/status/outcome +
+    # tranche vocab so the run can maintain the card as it advances.
+    stages:
+      - { key: identify, name: Identify, description: "Understand the project and which of the program's submission tracks fit — before any writing.", goal: "A clear project understanding and the fitting submission track; submission stage = scope." }
+      - { key: draft, name: Draft, description: "Write the abstract, then the full proposal, from the client's real material.", goal: "Abstract then full proposal drafted; submission stage abstract → build with body fields filled." }
+      - { key: submit, name: Submit, description: "Finalize against the program deadline and submit the application.", goal: "Application submitted on time; submission stage = awaiting-results." }
+      - { key: awaiting, name: Awaiting, description: "Track the decision and keep the client status current.", goal: "Submission status reflects where the decision stands (in-review / waiting-client / needs-document / blocked)." }
+      - { key: awarded, name: Awarded, description: "Record the funder's decision and the awarded amount.", goal: "Submission outcome set (awarded / rejected / partial) with the awarded amount." }
+      - { key: delivering, name: Delivering, description: "Work the program's tranche model — ship and record each tranche.", goal: "Tranche deliverables filled and trancheCompletion updated as milestones ship." }
+    executor: is-agent
+    grants:
+      - entity.create
+    status: active
+
+# Makes the spine ALIVE: a daily maintenance run that keeps each grant
+# application's `grant_submission` card current (advances stage + status) — the
+# durable, kanban-visible state of record. Generalizes the Stellar CP "Client
+# Sync" automation (read comms → assess → advance submission) into a chain-
+# AGNOSTIC workspace-template automation: it advances using grant_submission's
+# OWN stage/status vocab, so it works for any program (no Stellar-specific
+# assumptions). Same fan-out-safe shape the corpus uses (cron → in-flow `query`
+# → `loop`), NOT the `inputStrategy:'query'` playbook fan-out (which has the
+# known gap).
+automations:
+  - key: grant-submission-sync
+    name: Grant Submission Sync
+    description: >-
+      Once a day, keep each grant application's grant_submission card current —
+      read the submission's recent activity, assess where the pursuit stands, and
+      advance its stage + status so the pipeline stays the durable, kanban-visible
+      state of record.
+    triggerType: cron
+    triggerConfig:
+      expression: "0 8 * * *"
+    # DRAFT by default (deliberate safety): this runs a paid AI assess per
+    # grant_submission every day, so installing the suite must NOT silently start
+    # paid runs. Flip to `active` to let the pipeline self-maintain — same
+    # enabled-off-by-default convention as the radar / CRM-hygiene playbooks.
+    status: draft
+    metadata:
+      templateKey: grant-submission-sync
+    flow:
+      nodes:
+        - id: trigger
+          type: trigger
+          position: { x: 0, y: 0 }
+          data:
+            label: Daily at 08:00
+            triggerType: cron
+            config:
+              expression: "0 8 * * *"
+
+        # READ-ONLY builtin + SELECTION. The grant_submission cards ARE the grant
+        # pursuits (each is created by the `Grant Process` playbook at pursuit
+        # start), so querying them directly is the safe selection: it touches ONLY
+        # real pursuits and never fabricates a card for a non-grant contract.
+        #
+        # ── CREATE-IF-MISSING (deferred, flagged) ────────────────────────────
+        # The Stellar reference does create-if-missing by querying its subject
+        # (companies) and upserting the submission. Generalizing that safely means
+        # selecting "contracts that PURSUE a grant program" — but `entity.query`
+        # filters JSONB PROPERTIES only, it cannot filter by a `pursues` EDGE, and
+        # there is no query-fan-out capability to enumerate edge-linked subjects.
+        # Querying ALL contracts and creating a card per contract would spuriously
+        # create submissions for every non-grant engagement. So creation stays the
+        # `Grant Process` playbook's job (the agent creates the card when a pursuit
+        # begins) and this automation MAINTAINS. Fully-generalized create-if-
+        # missing needs an edge-aware selection capability that does not exist yet.
+        - id: list-submissions
+          type: capability
+          position: { x: 0, y: 120 }
+          data:
+            label: List grant submissions to maintain
+            verbId: entity.query
+            inputMapping:
+              profileSlug: grant_submission
+              limit: "100"
+
+        - id: submissions-loop
+          type: loop
+          position: { x: 0, y: 240 }
+          data:
+            label: For each grant submission
+            iteratorExpression: steps.list-submissions.output.entities
+            itemVariable: submission
+
+        # READ-ONLY builtin. Recent activity on THIS submission's thread — the raw
+        # signal the assess pass reads to place the pursuit's stage/status.
+        - id: read-activity
+          type: messages_query
+          position: { x: 0, y: 360 }
+          data:
+            label: Read the submission's recent activity
+            subjectEntityId: "{{loop.item.id}}"
+            limit: 40
+
+        # READ-ONLY (pure compute). ONE assess pass → STRICT JSON naming the
+        # submission's current stage + status, constrained to grant_submission's
+        # OWN enum vocab so it maps straight back onto the card (chain-agnostic).
+        - id: assess
+          type: capability
+          position: { x: 0, y: 480 }
+          data:
+            label: Assess the submission's stage + status → JSON
+            verbId: ai.generate
+            inputMapping:
+              json: "true"
+              maxTokens: "500"
+              system: >-
+                You are a strict data-extraction function for a grants pipeline.
+                Read a grant application's recent activity and report where the
+                application currently stands. Respond with STRICT JSON and NOTHING
+                else. Never fabricate — if the activity does not clearly indicate a
+                value, keep the submission's current one.
+              prompt: >-
+                The grant submission: {{loop.item.title}}
+                Current stage: {{loop.item.properties.stage}}
+                Current status: {{loop.item.properties.status}}
+
+                Recent activity (oldest first):
+                {{steps.read-activity.output.messages}}
+
+                Report the submission's current state as STRICT JSON, using ONLY
+                these vocabularies and NOTHING else:
+                {
+                  "stage": "scope|abstract|build|awaiting-results",
+                  "status": "answered|waiting-client|needs-document|in-review|blocked"
+                }
+
+        # GOVERNED WRITE via `output/entity_update` — advances the card's stage +
+        # status (the durable, kanban-visible state). Governed like every output
+        # write: routes to a proposal for review unless auto-approved.
+        - id: advance-submission
+          type: output
+          position: { x: 0, y: 600 }
+          data:
+            label: Advance the submission stage + status
+            outputType: entity_update
+            config:
+              entityId: "{{loop.item.id}}"
+              properties:
+                stage: "{{steps.assess.output.stage}}"
+                status: "{{steps.assess.output.status}}"
+      edges:
+        - { id: gs-trigger-list, source: trigger, target: list-submissions }
+        - { id: gs-list-loop, source: list-submissions, target: submissions-loop }
+        - { id: gs-loop-read, source: submissions-loop, target: read-activity }
+        - { id: gs-read-assess, source: read-activity, target: assess }
+        - { id: gs-assess-advance, source: assess, target: advance-submission }
+
 app:
   kind: stored
   cellKey: entity-detail

package/src/life-os.yaml

@@ -207,7 +207,12 @@ profiles:
     icon: User
     color: "#06B6D4"
     description: People in your intellectual and professional world.
-    scope: WORKSPACE
+    # Pod-wide identity: `person` is ONE pod-wide SYSTEM kind, not a life-os-local
+    # copy. `entityScope: pod` lands the ROWS with `workspace_id = NULL` (visible
+    # from every workspace); `scope` omitted (no claim) so the applier reuses the
+    # system row and these life-os props land as this workspace's OVERLAY.
+    # (Was `scope: WORKSPACE`, which contradicted the pod-wide model.)
+    entityScope: pod
     properties:
       - slug: name
         label: Name

package/src/networking.yaml

@@ -212,6 +212,11 @@ profiles:
     description: A company or person that provides a capability The Arch can broker a client need against.
     scope: shared
     profileKind: role
+    # Shared supply-role category — the intro-matcher's roster is now
+    # entity.query { roleCategory: "provider" }, spanning EVERY role tagged
+    # "provider" (this one in a public install; + blockchain-ecosystem's web3
+    # supply roles when The Arch installs both). One string, kept in sync there.
+    roleCategory: provider
     applicableKinds:
       - company
       - person
@@ -365,15 +370,21 @@ automations:
               limit: "100"
 
         # READ-ONLY builtin. The provider roster to match against — companies /
-        # people wearing the pod-wide `solution-provider` role.
+        # people wearing ANY role tagged `roleCategory: "provider"`. Dynamic by
+        # design: a public install matches its `solution-provider`s; The Arch
+        # (which also installs blockchain-ecosystem) additionally matches the web3
+        # supply roles; any future supply role tagged "provider" auto-joins with
+        # ZERO edits here. No `profileSlug` → no per-role hardcoding, no dependency
+        # on blockchain-ecosystem (a public installer simply has no web3 roles to
+        # match, so nothing leaks).
         - id: list-providers
           type: capability
           position: { x: 0, y: 240 }
           data:
-            label: List the solution-provider roster
+            label: List the provider roster (any roleCategory=provider)
             verbId: entity.query
             inputMapping:
-              profileSlug: solution-provider
+              roleCategory: provider
               limit: "100"
 
         - id: needs-loop

package/src/operations.yaml

@@ -212,6 +212,22 @@ entityLinks:
     targetProfileSlug: company
     type: briefing_about_client
     label: Client
+  # The CRM → Operations handoff edge. A `client` is a ROLE facet on a company
+  # OR a person (foundation's `applicableKinds`), so both endpoint pairs are
+  # declared — a solo-trader client is a person, and the pickup automation must
+  # be able to link its engagement either way.
+  - sourceProfileSlug: engagement
+    targetProfileSlug: company
+    type: engagement_for_client
+    label: Client
+  - sourceProfileSlug: engagement
+    targetProfileSlug: person
+    type: engagement_for_client
+    label: Client
+  - sourceProfileSlug: contract
+    targetProfileSlug: engagement
+    type: contract_for_engagement
+    label: Engagement
 
 # CURATED views — the delivery motion, not one per profile
 views:
@@ -571,3 +587,257 @@ automations:
         - { id: e-write-link, source: write-briefing, target: link-briefing }
         - { id: e-link-resolve, source: link-briefing, target: resolve-team }
         - { id: e-resolve-post, source: resolve-team, target: post-recap }
+
+  # ══════════════════════════════════════════════════════════════════════════
+  # CRM → Operations HANDOFF PICKUP
+  #
+  # The other half of business-developer's "Win and hand off". That flow ends by
+  # attaching the pod-wide `client` role with `handoffStatus`; nothing on the
+  # delivery side ever picked it up, so a won deal became a client and then
+  # nothing happened. This automation is that pickup: once a day it finds
+  # clients marked ready/handed_off that have NO engagement yet, and opens the
+  # delivery shell — a `proposed` engagement plus a `draft` contract.
+  #
+  # WHY THE SHARED `client` SLUG MATTERS: this reads foundation's pod-wide
+  # `client` role. When the CRM wrote a workspace-scoped `crm-client` instead,
+  # this query could not have seen a single handed-off party — the two halves of
+  # the handoff were spelling the same concept differently. Collapsing the fork
+  # is what makes this automation possible at all.
+  #
+  # WHY EVERY NODE TYPE IS WHAT IT IS (loop-body grammar, automation-executor.ts
+  # `LOOP_BODY_NODE_TYPES`): the per-client body may only contain
+  # command / output / condition / skill / capability / playbook_run /
+  # messages_query / query / fetch / transform. `switch`, `entity_read` and
+  # `related_entities` are BOUNDARY types — putting one in the chain would end
+  # the loop body there and silently run the rest ONCE for the whole run. That
+  # is why the two gates are `condition` nodes (per-item continue-semantics) and
+  # why the "does an engagement already exist?" lookup is a `capability`
+  # entity.query rather than a `related_entities` node.
+  #
+  # IDEMPOTENCY is per-client and does not rely on the gate alone:
+  # `dedupeBy: engagement-client` makes a second run for the same client a
+  # no-op SKIP before the governance gate is even reached, and the contract
+  # dedupes on `contract-engagement`. Both keys are real property defs on the
+  # profiles above, not invented ones.
+  #
+  # ── GOVERNANCE, HONESTLY ──────────────────────────────────────────────────
+  # `metadata.governance.forceProposeWrites` is deliberately NOT set here, and
+  # that is not an oversight. That marker is read in exactly ONE place —
+  # `deriveSessionForceProposeGovernance` (synap-backend
+  # `packages/api/src/utils/permission-check.ts`), off a FOCUS SESSION stamped
+  # by `executePlaybookRun`. It is a PLAYBOOK mechanism. A flow automation's
+  # `output/entity_create` goes through `checkAutomationWriteOrPropose`
+  # (packages/jobs/src/utils/automation-governance.ts), which never looks at
+  # automation metadata, so the field would be inert decoration. Worse: the
+  # automation propose path is currently BROKEN end-to-end (proposeAutomationWrite
+  # persists `data` FLAT while the approve executor reads a nested envelope —
+  # documented at automation-executor.ts, "KNOWN PRE-EXISTING BUG"), so forcing
+  # proposals here would produce reviews that throw on approve.
+  #
+  # The reviewability is carried by STATE instead: the engagement is created
+  # `proposed` and the contract `draft`. Nothing is active until a human moves
+  # it. If genuine proposal-gating is wanted, the canonical door is a PLAYBOOK
+  # with `metadata.governance.forceProposeWrites: true` + a `schedule` (the CRM
+  # Hygiene precedent in crm.yaml) — a different, agent-authored design.
+  # ══════════════════════════════════════════════════════════════════════════
+  - key: operations-crm-handoff-pickup
+    name: Pick up handed-off clients
+    description: >-
+      Daily. Finds pod-wide clients the CRM marked ready or handed off that have
+      no engagement yet, and opens the delivery shell for them — a proposed
+      engagement plus a draft contract, both linked to the client. Deduped per
+      client, so it is safe to re-run.
+    triggerType: cron
+    triggerConfig:
+      expression: "0 7 * * *"
+    status: active
+    metadata:
+      templateKey: operations-crm-handoff-pickup
+      # Same pod-wide dependency as the briefing automation: `client` entities
+      # are pod-wide, and `scope: pod` is the explicit opt-in that must be
+      # DEPLOYED for this query to return anything.
+      requiresPodWideEntityQueryLens: true
+    flow:
+      nodes:
+        - id: trigger
+          type: trigger
+          position: { x: 0, y: 0 }
+          data:
+            label: Daily at 07:00
+            triggerType: cron
+            config:
+              expression: "0 7 * * *"
+
+        # READ-ONLY builtin. Enumerates parties carrying the pod-wide `client`
+        # ROLE. `scope: pod` is required — see the long note on the briefing
+        # automation's `list-clients` node.
+        - id: list-clients
+          type: capability
+          position: { x: 0, y: 120 }
+          data:
+            label: List clients (pod-wide `client` role)
+            verbId: entity.query
+            inputMapping:
+              profileSlug: client
+              scope: pod
+              limit: "100"
+
+        - id: handoff-loop
+          type: loop
+          position: { x: 0, y: 240 }
+          data:
+            label: For each client
+            iteratorExpression: steps.list-clients.output.entities
+            itemVariable: client
+
+        # READ-ONLY builtin. `handoffStatus` lives on the client FACET row, not
+        # on the entity — `entity.query`'s `filter` reads `entities.properties`
+        # and therefore cannot see it. This is the only door that returns facet
+        # overlay properties.
+        - id: read-client-facets
+          type: capability
+          position: { x: 0, y: 360 }
+          data:
+            label: Read this party's role facets
+            verbId: entity_facet.list
+            inputMapping:
+              entityId: "{{loop.item.id}}"
+
+        # Pull the CLIENT facet's handoffStatus out BY SLUG. Positional
+        # indexing (`facets.0.properties…`) would be a latent bug: facet order
+        # is not guaranteed, so on a party that is also a partner it would read
+        # the wrong row. `filter` + `map` resolves it by identity.
+        - id: client-handoff-status
+          type: transform
+          position: { x: 0, y: 480 }
+          data:
+            label: Read the client facet's handoff status
+            expression: "{{steps.read-client-facets.output.facets}} | filter:item.profileSlug === client | map:{{item.properties.handoffStatus}}"
+
+        # PER-ITEM FILTER (continue-semantics). `pending` means the CRM has not
+        # finished with this client yet — only ready/handed_off are ours.
+        - id: handoff-gate
+          type: condition
+          position: { x: 0, y: 600 }
+          data:
+            label: Only clients the CRM marked ready or handed off
+            expression: "steps.client-handoff-status.output.result contains-any ready,handed_off"
+
+        # Pure read, workspace-lensed (engagements are Operations-local, so no
+        # `scope: pod`). `engagement-client` is a real property def above, so
+        # this equality filter hits `entities.properties`.
+        #
+        # `filter` is authored as a JSON *STRING*, not a mapping, and that is
+        # load-bearing: `parseQueryFilterConditions` (automation-executor.ts)
+        # template-resolves the filter ONLY when it is a string. Written as a
+        # YAML object, `{{loop.item.id}}` would reach SQL as that literal text,
+        # match nothing, and this gate would then open for EVERY client.
+        - id: existing-engagements
+          type: query
+          position: { x: 0, y: 720 }
+          data:
+            label: Does this client already have an engagement?
+            profileSlug: engagement
+            filter: '{"engagement-client": "{{loop.item.id}}"}'
+            limit: 1
+
+        - id: engagement-gate
+          type: condition
+          position: { x: 0, y: 840 }
+          data:
+            label: Only clients with no engagement yet
+            expression: "steps.existing-engagements.output.count === 0"
+
+        # Cron trigger carries no payload timestamp, so `now` falls back to the
+        # actual run time — stamping the handoff moment onto both records
+        # below so they plot on the calendar the day they're handed off.
+        # `engagement-end`/`start`-adjacent dates the owner still sets by hand
+        # stay unset.
+        - id: handoff-time
+          type: compute
+          position: { x: 0, y: 900 }
+          data:
+            label: Record handoff time
+            operation: now
+
+        # GOVERNED WRITE via an `output` node. Created `proposed`, never active:
+        # the delivery shell exists so the work is visible, but a human decides
+        # when it starts. `dedupeBy: engagement-client` is the durable
+        # per-client idempotency key — a re-run SKIPS before the governance gate.
+        - id: create-engagement
+          type: output
+          position: { x: 0, y: 960 }
+          data:
+            label: Open a proposed engagement
+            outputType: entity_create
+            config:
+              profileSlug: engagement
+              title: "Engagement — {{loop.item.title}}"
+              dedupeBy: engagement-client
+              properties:
+                engagement-status: proposed
+                engagement-client: "{{loop.item.id}}"
+                engagement-start: "{{steps.handoff-time.output.result}}"
+                engagement-notes: "Opened automatically from the CRM handoff. Confirm scope, dates, and owner before activating."
+
+        - id: link-engagement
+          type: output
+          position: { x: 0, y: 1080 }
+          data:
+            label: Link engagement → client
+            outputType: relation_create
+            config:
+              fromEntityId: "{{steps.create-engagement.output.entityId}}"
+              toEntityId: "{{loop.item.id}}"
+              relationType: engagement_for_client
+
+        # Draft contract, deduped on the engagement it governs. A skipped
+        # (duplicate) engagement create still returns the existing entityId, so
+        # this stays correctly anchored on a partial re-run.
+        - id: create-contract
+          type: output
+          position: { x: 0, y: 1200 }
+          data:
+            label: Open a draft contract
+            outputType: entity_create
+            config:
+              profileSlug: contract
+              title: "Contract — {{loop.item.title}}"
+              dedupeBy: contract-engagement
+              properties:
+                contract-status: draft
+                contract-engagement: "{{steps.create-engagement.output.entityId}}"
+                start-date: "{{steps.handoff-time.output.result}}"
+                contract-notes: "Drafted automatically from the CRM handoff. Attach the signed document and set the term."
+
+        - id: link-contract
+          type: output
+          position: { x: 0, y: 1320 }
+          data:
+            label: Link contract → engagement
+            outputType: relation_create
+            config:
+              fromEntityId: "{{steps.create-contract.output.entityId}}"
+              toEntityId: "{{steps.create-engagement.output.entityId}}"
+              relationType: contract_for_engagement
+      edges:
+        - { id: h-trigger-list, source: trigger, target: list-clients }
+        # `handoff-time` is a `compute` node, and `compute` is NOT a per-item
+        # loop-body type — the executor's body walk STOPS at it. Sitting inside
+        # the loop chain it severed the body, orphaning create-engagement /
+        # link-engagement / create-contract / link-contract into the main pass
+        # where `{{loop.item.id}}` resolved to undefined (empty-id entities and
+        # relations). It is a RUN-level timestamp, identical for every item, so
+        # it belongs before the loop; `{{steps.handoff-time.output.result}}`
+        # still resolves from inside the body because step outputs are global.
+        - { id: h-list-time, source: list-clients, target: handoff-time }
+        - { id: h-time-loop, source: handoff-time, target: handoff-loop }
+        - { id: h-loop-facets, source: handoff-loop, target: read-client-facets }
+        - { id: h-facets-status, source: read-client-facets, target: client-handoff-status }
+        - { id: h-status-gate, source: client-handoff-status, target: handoff-gate }
+        - { id: h-gate-existing, source: handoff-gate, target: existing-engagements }
+        - { id: h-existing-gate, source: existing-engagements, target: engagement-gate }
+        - { id: h-gate-engagement, source: engagement-gate, target: create-engagement }
+        - { id: h-engagement-link, source: create-engagement, target: link-engagement }
+        - { id: h-link-contract, source: link-engagement, target: create-contract }
+        - { id: h-contract-link, source: create-contract, target: link-contract }