Approval flows F1–F3 + the `automation` capability

[os-sam]

Card docs/backlog/11-approval-flows.md · Milestone M3 · Blocked-by: M1 (PR #1)

Scope

src/flows/employer-verification.flow.ts, job-publish-review.flow.ts, offer-approval.flow.ts, barrel, wire flows; add 'automation' to requires: in objectstack.config.ts.

This card is the one that expands that capability — AGENTS.md keeps capability expansion tight, so no other dependency, plugin or requires: entry comes with it. Load objectstack-automation (approvals, approval-as-flow-node) and study examples/app-showcase/src/automation/flows/ in the objectstack repo.

Spec — DESIGN.md §05

• F1 employer_verification — entry when ats_employer.verification_status becomes pending; step 1 approver = position platform_ops, step 2 = platform_admin; approve → verified + notify the employer owner (inbox); reject → rejected, copy the reviewer's comment to verification_note. That note is platform-internal and FLS-masked from employer roles, so the rejection reason the employer sees must not be sourced from it.
• F2 job_publish_review — entry on ats_job.status → pending_review; single approver position platform_ops; approve → published + published_at = now; reject → rejected + rejection_reason from the reviewer comment; notify the job's employer members with access_level == 'admin'.
• F3 offer_approval — entry on ats_offer.status → pending_approval; approver = the employer_admin members of the offer's employer; approve → approved; reject → draft; notify the submitter. This one is the employer's own internal approval — it demonstrates that approval chains are not only a platform-operator device.

Every transition must be legal under the state machines in §02. Do not widen a state machine to make a flow fit — if a flow needs a transition that does not exist, that is a needs_decision.

Also in scope

Org provisioning on approval: when F1 approves an employer, its platform organization and the owner's membership must exist, or every subsequent row-level policy for that employer resolves to zero rows (DESIGN.md §03, "遗留的运维前提"). Seeds cover this for the demo data; F1 covers it for real onboarding.

Acceptance

• pnpm validate && pnpm lint && pnpm typecheck green; pnpm validate reports 3 flows.
• In pnpm dev the three approvals appear in the approver's queue; a rejected job carries rejection_reason.

Out of scope

Email channel configuration; F4–F6 (#7).

[os-sam]

Claim: session_01PbJ5Cy9KDAzeQHo8bsMadG · branch claude/issue-6-approval-flows

Dispatched by the PM loop as part of batch 1 (#2, #5, #6 — disjoint by directory). The developer agent inherits this claim and the assignee; it posts no second claim and does not touch the assignee field.

Shared-file warning for the dev: objectstack.config.ts is being edited by two sibling PRs in flight right now. This card is the one authorised to extend requires: — add 'automation' and update the // automation is added in M3 comment above it, plus the flows: key and its src/flows/index.js import. Nothing else in that file. #2 adds views:, #5 adds the seed/data key. Expect to merge origin/main before this lands; the conflict is a one-line import, not a semantic one.

#7 is deliberately NOT in this batch — it also edits requires:, so it is serialized behind this card.

---

Generated by Claude Code

[claude]

os-dev-report

{
  "issue": 6,
  "status": "done",
  "branch": "claude/issue-6-approval-flows",
  "pr": "https://github.com/objectstack-ai/ats/pull/15",
  "premise_still_valid": true,
  "summary": "Delivered the three approval chains (F1 employer_verification: platform_ops then platform_admin; F2 job_publish_review: platform_ops; F3 offer_approval: the offer's employer admin members) as record_change flows with reject branches that copy the reviewer's sys_approval_action comment onto verification_note / rejection_reason, inbox notifications on every branch, and approved_by on F3 approve; every write is a transition the state machines already allow. Config touched only requires, its comment, flows and the import. One premise of the card is false and needs the maintainer's nod: requires cannot be ['ui','automation'] alone, because defineStack itself refuses record_change flows without 'triggers' (validate exit 1, error quoted in the PR), 'approvals' is the only provider of the approval node executor and without 'messaging' notify silently delivers nothing, so the branch declares ['ui','automation','triggers','approvals','messaging'] with zero package changes (all providers ship with the CLI). Runtime acceptance was verified against a LOCAL, uncommitted body-form stand-in for the stamp hooks (src/hooks is byte-identical to origin/main in the PR) because #10 makes every write on ats_job / ats_offer / ats_application / ats_employer_member answer 500 on a clean boot: all three requests appear in the Console Approvals Inbox (My Pending 3, screenshot taken), F2 reject carries rejection_reason verbatim, F2 approve publishes with published_at, F3 approve/reject and F1 approve/reject all land with their inbox messages, every run completed. F1 also holds on a clean origin/main boot (no stamp hook on ats_employer). PM question answered: yes, under the real hooks the flows' OWN writes die too — staged the requests hook-free on sqlite, rebooted with hooks, granted the approvals: F2 'publish_job' and F3 'approve_offer' fail with update_record(...) failed: hook 'ats_job_stamp' / 'ats_offer_stamp' threw: TypeError: cannot read property 'find' of undefined, the run is stranded and the record stays pending, so #10 blocks F2/F3 from working at all on main, not only the demo. Claim comment verified naming this branch; assignee untouched.",
  "tests": "pnpm validate: exit 0, 'Validation passed', 'Logic: 3 Flows', 3 info suggestions (approval-approvers-may-resolve-empty on the position-routed nodes). pnpm lint: exit 0, '3 suggestion(s)', no warnings after wrapping the per-member notify in try_catch. pnpm typecheck (tsc --noEmit): exit 0. Final tree b92d40c, logs kept (validate-final.log / lint-final.log / typecheck-final.log), tails pasted in the PR. Negative control: with requires ['ui','automation'] validate exits 1 with 'defineStack trigger capability validation failed (3 issues)'. Runtime (17.3.0, pnpm dev --fresh --database-driver memory, local hook stand-in): queue shows Offer Approval / Job Publish Review / Employer Verification; job after reject {status: rejected, rejection_reason: 'Salary range is missing and the description names a specific school.'}; job2 after approve {status: published, published_at: 2026-09-07T01:11:10.502Z}; offer after approve {status: approved, approved_by: admin id}; offer2 after reject {status: draft}; employer after two approvals {verification_status: verified}; employer2 after reject {verification_status: rejected, verification_note: 'Registration number does not match the licence.'}; 5 sys_inbox_message rows with the expected titles; all runs completed; 0 pending. Two-boot probe on sqlite (hook-free artifact then real artifact): F2/F3 runs failed at publish_job / approve_offer with the #10 hook error. No ablation: the repo has no test suite and the gates are static; the probe swapped dist/objectstack.json (gitignored) and restored it, verified byte-identical with cmp; the temporary hook stand-in was reverted with git checkout HEAD and is byte-identical to the pre-patch copy.",
  "mcp_calls": "0 — every GitHub read and write (issue list/reads, issue #12 create + duplicate-close + comment, issue #14 create, PR #15 create, this report comment) went through the proxy-authenticated REST channel; the search endpoint returned no totals for both target and control queries, so the duplicate check used the exhaustive open-issue list of this 10-issue repo instead.",
  "open_questions": [
    {
      "question": "requires slate: the card authorises only 'automation'; the platform demands 'triggers' (hard validate error), 'approvals' (approval node executor) and 'messaging' (inbox delivery). Accept the four-token slate declared in PR #15?",
      "options": [
        "A — accept ['ui','automation','triggers','approvals','messaging'] as declared: gates green, no new package, acceptance criteria reachable; #7 later adds 'job' for F5/F6.",
        "B — ['ui','automation','triggers','approvals'] without messaging: gates green but every notify node reports success while delivering nothing (skipped: true) — a silent stub, which the dispatch explicitly forbade.",
        "C — keep the card's letter ['ui','automation']: validate exits 1, the flows can never fire; the card is undeliverable."
      ],
      "recommendation": "A, because it is the only slate under which the card's own gate passes and its acceptance (approvals in the queue, inbox messages) is real; the providers already ship with the CLI so the cost is one line."
    },
    {
      "question": "F3 approver reading: 'the employer_admin members of the offer's employer' is implemented as the ats_employer_member rows with access_level == 'admin' for the offer's employer (get_record by the stamped employer scalar, folded to a CSV slate). The alternative is { type: 'position', value: 'employer_admin' }, which the runtime scopes to the request's organization. Keep the member-row slate?",
      "options": [
        "A — keep the member-row slate (as shipped): exact regardless of tenancy posture, same pivot F2 uses for its audience, verified end to end; costs three extra nodes.",
        "B — switch to the position approver: one line, consistent with F1/F2, but a cross-employer slate until every employer is its own organization and positions are provisioned per org."
      ],
      "recommendation": "A, because an offer approval routed to another employer's administrator is a write-side isolation breach and the member table is the boundary that holds today; revisit when the org-per-employer provisioning of DESIGN.md §03 lands."
    }
  ],
  "out_of_scope_findings": [
    "filed as #14: ats_employer_member has no employer_org field, yet the member stamp hook writes it and the employer_admin_members / recruiter_members row-level policies read it — surfaces as INVALID_FIELD one step after the #10 fix; two consistent resolutions and a recommendation in the issue.",
    "#10 (pre-existing, filed by the #2 agent at 01:04Z): stamp hooks call ctx.ql inside the lowered sandbox body — my #12, filed a minute later from an issue list taken before #10 existed, is closed as duplicate of #10; new evidence added here: the flows' own update_record writes on ats_job / ats_offer fail through the same hook, so #10 blocks F2/F3 outright.",
    "not filed (tenancy-posture question for DESIGN.md §03, PM to decide): position approvers resolve against the request's organization (sys_user_position.organization_id = the submitter's active org). Under org-per-employer, platform_ops / platform_admin must hold their positions in each employer org or be routed via the approver 'organization' field, otherwise F1/F2 land in admin rescue.",
    "observation, not a defect: rows seeded directly in pending / pending_review / pending_approval (#5 seeds) carry no approval request because the flows fire on the transition (record-after-update); the showcase launches such demo requests by hand."
  ]
}

---

Generated by Claude Code