Skip to main content

Step Functions Workflow — Scintilla Locate AI Software Factory (MVP)

last updated: 2026-03-01

This document defines the exact AWS Step Functions state machine for the MVP Scintilla Locate AI Software Factory.

It implements the handbook doctrine:

  • Specs are authority (agents propose; humans approve)
  • Deterministic transforms are tool-driven (never “in-model”)
  • Every run is auditable (immutable run ledger with hashes)
  • Least privilege (agents can open PRs, not merge)

MVP outcome​

The MVP is sufficient to build the Meetup Badge demo and a minimal Round Publisher implementation:

  • plan work from a Jira issue
  • generate candidate changes on a feature branch
  • run deterministic verification (lint/build/IR/verify, tests, vectors)
  • open a PR/MR with evidence attached
  • request human approvals (Spec / Plan / Risk / Release)

Services​

  • Step Functions (workflow engine)
  • ECS Fargate (planner/builder/verifier tasks)
  • S3 (artifact store; content-address when possible)
  • DynamoDB (run ledger index)
  • KMS (encryption)
  • EventBridge (triggers)
  • SNS/Slack (notifications)

Entry input contract​

{
  "run_id": "pf-<ulid>",
  "trigger": {
    "type": "jira_issue",
    "key": "LOCATE-123",
    "url": "https://...",
    "project": "LOCATE",
    "labels": ["sdd", "factory", "demo"],
    "risk_class": "medium"
  },
  "repos": [
    {
      "name": "locate-round-publisher",
      "provider": "gitlab|github",
      "url": "https://...",
      "default_branch": "main"
    }
  ],
  "policy": {
    "policy_version": "pf-policy-v1",
    "model_routing": "default",
    "allow_models": ["chatgpt", "gemini", "copilot", "grok"],
    "redaction": "strict"
  }
}

Run Ledger records (DynamoDB)​

Each step writes a ledger event with:

  • event type (phase_start, tool_result, model_output, approval_request, …)
  • SHA-256 hashes of inputs/outputs
  • S3 refs for large payloads (prompts/logs/evidence bundle)
  • Git refs (branch + commit hashes)

Human gates (MVP behavior)​

The MVP never merges. It:

  • opens a PR/MR
  • posts an approval checklist (Spec / Plan / Risk / Release)
  • links to evidence bundle (S3) + hashes (DynamoDB)

Later: a separate Release machine can run only after approvals are recorded.

Authoritative state machine​

See: infra/stepfunctions/protocol_factory_mvp.asl.json

Tasks​

Intake (Lambda)​

  • NormalizeInput
  • InitRunLedger
  • FetchJiraIssue
  • CreateWorkingBranch

Agents (ECS Fargate)​

  • PlannerAgent
  • BuilderAgent
  • VerifierAgent

PR + Evidence (Lambda/ECS)​

  • UploadEvidenceBundle
  • OpenPullRequest
  • NotifyApprovers

Failure (Lambda)​

  • FailAndBundle

Timeouts & retries​

  • Planner/Builder/Verifier: bounded timeout + exponential retry on infrastructure failures
  • Verification failure is not retried blindly; it bundles evidence and fails fast

Security notes​

  • Task roles grant least-privilege access (repo tokens via Secrets Manager)
  • No secrets are written into prompts
  • Container images are pinned by digest
  • Deterministic toolchain versions are pinned
Last updated on