Use the audit workflow example

The examples package includes a generic read-only audit workflow that fans out over feature groups, asks a harness to inspect each group, and then merges the structured findings deterministically in TypeScript.

Use it when you want a reusable repository audit shape without embedding audit-specific source paths or findings in Orchard itself.

Example project layout

A project that copies the example into its local Orchard workflow directory can look like this:

acme-service/
├── .orchard/
│   ├── config.json
│   └── workflows/
│       └── audit.ts
├── package.json
├── src/
│   ├── auth/
│   │   ├── session-store.ts
│   │   └── token-policy.ts
│   ├── payments/
│   │   ├── ledger.ts
│   │   └── settlement.ts
│   └── observability/
│       └── audit-events.ts
└── test/
    ├── auth.test.ts
    └── payments.test.ts

Copy packages/examples/src/audit.ts into .orchard/workflows/audit.ts, or use it as the construction reference for an CLI-generated workflow artifact.

What the workflow does

The workflow has three memoized in-process stages:

1. audit-groups runs a bounded read-only fan-out over feature groups.
2. absurd-agents.audit-worker runs one structured harness call for each group.
3. merge-audit deterministically sorts and merges the group outputs without a merge-model call.

The worker uses access: 'read' and rejects non-read Orchard access headers. The fan-out task and worker task use distinct queue labels: queues.tasks for the parent task and ${queues.tasks}-workers for child audit workers. These labels are part of the generated-artifact contract and make the topology readable; the in-process runtime records them as metadata only.

Example input

{
  "cwd": "/absolute/path/to/acme-service",
  "focus": "production readiness and security review",
  "maxConcurrency": 2,
  "features": {
    "auth-session-boundaries": [
      "src/auth/session-store.ts",
      "src/auth/token-policy.ts",
      "test/auth.test.ts"
    ],
    "payments-ledger-settlement": [
      "src/payments/ledger.ts",
      "src/payments/settlement.ts",
      "test/payments.test.ts"
    ],
    "audit-observability": [
      "src/observability/audit-events.ts",
      "src/payments/settlement.ts"
    ]
  },
  "additionalContext": "Focus on concrete source-backed findings. Ignore generic trust assumptions unless they create an actionable invariant or operational gap."
}

Run it

After the project has Orchard initialized, run the workflow artifact:

pnpm exec orchard run .orchard/workflows/audit.ts \
  --harness codex \
  --input-json "$(cat audit-input.json)" \
  --json

The output shape is stable for downstream reports:

{
  "summary": "Audited 3 feature groups and found 2 findings. Highest severity: medium.",
  "totalGroups": 3,
  "findingCount": 2,
  "highestSeverity": "medium",
  "findings": [
    {
      "group": "auth-session-boundaries",
      "severity": "medium",
      "title": "Session expiry accepts stale tokens",
      "evidence": "src/auth/token-policy.ts:42",
      "impact": "Expired sessions can remain valid longer than intended.",
      "recommendation": "Check token expiry before session refresh and add a regression test."
    }
  ]
}

Testing guidance

Repository tests should verify construction contracts, not execute the real audit against a production repository. The examples package tests assert stable task names, queue wiring, read-only/model header propagation, and deterministic merge behavior with fake apps and fake harnesses.

Run real audits explicitly through orchard run from the target repository or a disposable copy with the target repository path supplied in cwd.