Workflow Playbook Spec Builder 20260724

Overview

This net-new draft implements the 2026-07-24 Merlin workflow-playbook priority. Its stdlib-first analyzer reviews business-process trigger, owner, inputs, ordered steps, decisions, outputs, exceptions, permission boundaries, validation, approval, rollback, metrics, and handoff evidence.

It is advisory and read-only. It does not execute workflows, call connectors, generate executable code, install skills, publish, deploy, or mutate files. It does not certify downstream release, security, live, package, or production state.

When to Use

• Before acting on non-sensitive local notes about business-process trigger, owner, inputs, ordered steps, decisions, outputs, exceptions, permission boundaries, validation, approval, rollback, metrics, and handoff evidence.
• When a reproducible PASS, REVIEW, BLOCKED, or ERROR evidence-gap report is needed.
• To prepare clean, risky, missing, guarded-path, and oversized-input cases for independent Viper QA.

Safety Contract

• Reads only direct --text or one explicitly supplied local notes file.
• Refuses hidden or sensitive-looking paths, symlinks, non-files, and inputs over 200,000 characters.
• Uses Python standard-library modules only and reports mutated_files: [].
• Local PASS is advisory and is not independent approval.

Main Script

scripts/workflow_playbook_spec_builder.py supports --notes, --text, --self-test, and --json.

Operator Workflow

1. Prepare redacted, non-sensitive evidence notes; completion means no secrets or private personal data are present.

2. Run python3 scripts/workflow_playbook_spec_builder.py --notes notes.txt --json; completion means structured output is returned and source content is unchanged.

3. Assign every finding to an owner or explicit deferral; completion means no finding is silently ignored.

4. Hand unchanged artifacts and evidence to Viper while retaining PENDING_VIPER.

Result Semantics

• PASS: at least nine expected signals and no risk signal.
• REVIEW: partial evidence or one bounded concern.
• BLOCKED: at least two risks or evidence score below 25.
• ERROR: missing, guarded, oversized, or unreadable input.

Test Scenarios

• Complete expected evidence should produce PASS.
• Two or more explicit risk signals should produce BLOCKED.
• Missing input should return ERROR with missing_notes.
• Hidden, sensitive-looking, symlinked, directory, and oversized inputs should be refused without mutation.

Common Pitfalls

1. Treating local analyzer PASS as independent approval.

2. Supplying secret values instead of redacted evidence references.

3. Mistaking recommendations for authorized remediation.

4. Omitting rollback, ownership, or reviewer evidence.

Verification Checklist

• [ ] python3 -m py_compile scripts/workflow_playbook_spec_builder.py exits 0 with isolated bytecode output.
• [ ] --self-test --json returns ok=true, clean=PASS, risky=BLOCKED, and mutated_files=[].
• [ ] Input guards and repository security/static checks pass.
• [ ] Draft remains PENDING_VIPER.

Draft Status

PENDING_VIPER — Iceman build evidence is not an independent downstream verdict.