/sox-test

The bridge between a AssureSwarm workflow and the /sox-testing fieldwork engine. It operates the Test step of a SOX testing workflow hosted directly on a Control item: the workflow is the test, and there is no separate test item. The bridge pulls the step through get_step_context, then resolves and verifies the workflow’s Control host, template, and fiscal-year scope. The Control must have fields.sox_applicable === true as a literal boolean (never the string "true", never an inference from framework tags); the workflow’s template must have metadata.kind === "sox-testing"; and the testing cycle lives at Workflow.customFields.sox.fiscalYear, so multiple fiscal years are separate workflow instances on the same Control. It downloads the evidence gathered on the workflow’s stage steps (the sample list, the evidence folder, any prior-period workpaper); runs the engine on them; uploads the finished workpaper back to the step; publishes a structured results matrix alongside it; and proposes the step’s result fields via one suggestion a reviewer approves in Canvas. The division of labor is fixed: the workflow owns the process (assignments, due dates, reviewer sign-offs, step completion); this skill does the tick-and-tie mechanics at the fieldwork step and nothing more.

When to use

When a SOX control test runs as a workflow step in your tenant and you want the fieldwork done and its result proposed for human approval: the evidence assembled from Canvas, the engine run, the workpaper landed back on the step. To run the engine outside a tenant (no Canvas connector), use /sox-testing directly.

Inputs

Flag	Required	Notes
--step <step-id>	No	The Test step to operate. If absent, inferred from your current view or asked from your assigned steps.
--control <control-id-or-slug>	No	Alternative to --step: resolves the Control, requires literal sox_applicable === true, finds the workflow hosted directly on it whose template has metadata.kind === "sox-testing" and whose Workflow.customFields.sox.fiscalYear matches the requested cycle, and operates that workflow’s Test step.
--kind tod|toe	No	Test of design vs test of operating effectiveness; usually already captured in the step. Confirmed rather than assumed when both are plausible.
--period <YYYY-Q[1-4]>	No	Read from the step’s instructions or form when present; the tested period is a step-level fact, distinct from the workflow’s fiscal-year cycle.
--workpaper-dir <dir>	No	Where the engine’s workpaper and working files land locally. Defaults to workpapers/<control-id>/.

Example

/sox-test --step step_abc pulls the Test step’s context, resolves the sibling stage steps (Sample / Confirm attributes / Gather evidence / Upload past workpapers) and downloads their evidence, then runs /sox-testing with the assembled --samples / --prior / --evidence inputs. When the grader passes, it uploads the workpaper and a structured results file to the step and submits one submit_form suggestion filling the conclusion, exceptions count, and workpaper reference: pending your approval in Canvas.

Good to know

• It never advances or completes the step. No status change, no completed_at: the suggestion touches result fields only, and the reviewer’s sign-off in the workflow is what completes the step.
• The human approves in Canvas. The suggestion is a proposal; nothing is recorded until a reviewer approves it. That approval is the whole reason the bridge exists.
• Missing evidence triggers a PBC chase, not a guess. If the required inputs aren’t in yet, the skill records a missing-items note instead of building a workpaper on partial evidence, and offers to notify the control owner.
• Rejection re-entry reads the reviewer’s comment. On a re-run after a rejected suggestion, it routes on what the reviewer objected to, fixing the inputs and re-running, or revisiting the judgment calls with you, and never resubmits the identical proposal.
• Exception classification isn’t its call. It documents the exceptions but points you at the deficiency-evaluation workflow to classify them.
• It needs the shared core schema. Run /coach-starter-pack first if pre-flight fails; with no Canvas MCP connector at all, it stops and points you at /sox-testing.

Related

• /sox-testing: the fieldwork engine this bridge runs.
• /coach-document-upload: the upload primitive it uses to put the workpaper and results on the step.
• /coach-starter-pack: installs the shared core schema this skill requires.
• Builds on get_step_context, download_document, upload_document, and suggest_change (submit_form).

Not audit or legal advice. Workpapers and assessments produced by these skills require review by qualified financial professionals before being relied on for SOX 404 compliance.