sorrel/docs/workflows

Workflows, Vault, Slices

Execution and context: portable job bundles that travel with the work, secrets that exist only as references, and slice manifests that give an agent exactly the files it needs — all gated by Core policy decisions.

Portable workflows (sorrel-runners)

Workflows are declared in sorrel.workflow.yml: named workflows, jobs with commands, dependencies (needs), inputs, platforms, and environment. The parser converts a workflow into a portable JobBundle in deterministic topological order.

version: 1
workflows:
  validate:
    jobs:
      lint:
        command: npm run lint
      test:
        command: npm test
        needs: [lint]
        env:
          NPM_TOKEN:
            secretRef: secret_npm_token_dev

Bundles declare the capabilities they need (runner.use, workflow.run) and are authorized through Core's policy path before a single process starts. Local process execution works today; container-runtime jobs are representable in the model and execute later. A forged bundle that skips the policy gate is rejected — that path is covered by conformance tests.

Secrets as references (sorrel-vault)

Secret values never enter history, diffs, logs, or proposals. Workflows reference SecretRef handles; resolution happens at execution time through a backend, guarded by Core grant decisions (secret.read, secret.inject), and runner output is redacted against resolved values.

$ npm run vault -- import .env      # keys only — values are never persisted
$ npm run vault -- list             # SecretRef declarations + environments
$ npm run vault -- grant ...        # allow / deny / needs_grant decision
$ npm run vault -- redact run.log   # scrub resolved secrets from text

A local YAML file cannot bypass policy: vault operations evaluate the same Core decisions as everything else, and that equivalence is enforced by the shared conformance manifest.

Slices (sorrel-slices)

Agents rarely need a whole monorepo. A slice manifest describes a focused subproject: entry points, the files in its dependency closure, and what it exports. The current generator walks TS/JS projects; the CLI can also record generic slice manifests for other stacks. Slices become shareable, reviewable context units — "here is exactly what this agent saw."