BOHICA-LABS / BOHICA-LABS/vsdd-factory

enhancement(demo-recorder): add project-manifest `demo_artifact_format` knob (tape-only | tape+gif | tape+gif+webm) so projects that don't want rendered binaries in git can commit only .tape scripts

Open
#501 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
2
Forks
1
Avg merge
6h 43m
Merged PRs (30d)
29

Description

## Summary

`vsdd-factory:demo-recorder` hardcodes VHS→GIF+WebM output for every AC (see `agents/demo-recorder.md` L54-55, L97, and specifically L109: *"Both `.gif` + `.webm` — gif for PR embed, webm for archival. Always output both."*). There is no project-level configuration surface to opt out of rendered binaries in favor of `.tape`-only commits, and no orchestrator-level dispatch instruction to override the default.

**Severity:** MEDIUM (repo-hygiene footgun; accumulates binary bloat silently across per-story loops; no in-band signal that plugin default is at odds with project preferences).

## Trigger (concrete)

Filed from `ArcavenAE/switchboard-blue` on 2026-07-04. After `v0.1.0-rc.1` SHIPPED and through the Wave-6 + Phase-3 demo-recorder backfill (invoked routinely per `orchestrator/per-story-delivery.md` step 5 as "the normal demo cadence"), each invocation committed both a `.tape` script AND the rendered `.gif` and `.webm` for every AC.

Result: **62 tracked binaries totaling ~12,939,499 bytes (~12.3 MB)** accumulated under `docs/demo-evidence/S-5.02/`, `S-6.06/`, `S-6.07/`, `S-W5.04/`, `S-BL.LOOKUP/`, and other story dirs. Discovered when the maintainer asked *"is there a way to turn off the vhs rendering to gif bullshit in vsdd-factory? I really HATE pushing pointless media, images to my git repos"*.

## Root cause

- `agents/demo-recorder.md` L54-55, L97, L109 hardcode dual-format rendering (`always output both`).
- There is no:
- environment variable (`DEMO_ARTIFACT_FORMAT`, `VSDD_DEMO_NO_RENDER`, …),
- project-manifest / STATE.md frontmatter field,
- policy in the factory policies registry the agent consults,
- CLI flag on the agent's task prompt,
- documented escape hatch other than the Level-3 *"VHS unavailable"* escalation (which is a failure mode, not a project preference)

that lets a project opt out. The plugin default is universal across every vsdd-factory-managed repo.

## Failure scenario

Any project **(a)** that runs `demo-recorder` as a routine per-story artifact AND **(b)** whose maintainers prefer a lean git repo, accumulates rendered binaries indefinitely with no in-band warning.

- `git clone` size grows monotonically.
- `git diff` on the demo evidence dir is un-reviewable — reviewers cannot tell what changed between two GIFs.
- The `.tape` script is the only useful diff signal.
- The waste compounds because `demo-recorder` is invoked once per AC per story per fix-burst — for stories with 6-10 ACs, a single convergence cycle produces 12-20 binaries.

## Proposed fix (three-part)

### 1. Add a `demo_artifact_format` project-level configuration field

Recognised locations, in precedence order (amended 2026-07-05 per maintainer-feedback comment below — policies.yaml promoted to primary):

1. `.factory/policies.yaml` policy `demo-artifact-format` with `mode: "tape-only" | "tape+gif" | "tape+gif+webm"`. Rationale: this is a **stable project preference**, and policies.yaml is the durable per-project policy registry; `.factory/STATE.md` frontmatter is per-cycle volatile state and the wrong home for it.
2. Fallback: environment variable `VSDD_DEMO_ARTIFACT_FORMAT`.
3. Fallback: current default (`tape+gif+webm`, backward compatible).

### 2. Amend `agents/demo-recorder.md`

So the agent's dispatch reads the field on startup and skips the `vhs ` render step accordingly:

| Value | Behavior |
|-------|----------|
| `tape-only` | Write `.tape` scripts and `evidence-report.md`; do NOT run vhs; emit note in the AC evidence row that renders are gitignored / regenerable via `vhs /AC-NNN.tape`. |
| `tape+gif` | Write `.tape` and render `.gif` only. |
| `tape+gif+webm` | Current behavior (unchanged default). |

### 3. Update `orchestrator/per-story-delivery.md` §Step 5

- **Add:** "If the project's `demo_artifact_format` is `tape-only`, the orchestrator MUST include the verbatim override instruction in the demo-recorder task prompt: *'Repo policy: do not render or commit .gif/.webm/.mp4/.png. Commit .tape scripts and evidence-report.md only. If you need to verify a tape renders, do so locally; the rendered artifacts are gitignored under docs/demo-evidence/**.'*"
- ~~**Add** a `/vsdd-factory:demo-policy-check` skill~~ — **withdrawn 2026-07-05**: a step beyond the concrete need. The configuration knob (part 1) plus the agent honoring it (part 2) is the load-bearing fix; a consistency-check skill can be proposed separately if drift is ever actually observed.

## Supporting data point (added 2026-07-05)

The plugin repository itself dogfoods this default: the vsdd-factory repo carries **338 rendered `.gif`/`.webm`/`.mp4` files totalling ~61 MB** under `docs/demo-evidence/` on the current develop tip. This is not a hypothetical externality — the default's cost is visible in the factory's own tree, and is likely the strongest single piece of evidence that `tape+gif+webm`-always is at odds with common repo-hygiene preferences.

## Compatibility

Default remains `tape+gif+webm` so no existing project changes behavior. **Opt-in field.**

## Concrete evidence (from switchboard-blue)

- `.gitignore` diff excluding `docs/demo-evidence/**/*.{gif,webm,mp4,png,jpg,jpeg}` on `chore/no-demo-binaries` branch.
- `docs/DEMO-EVIDENCE-POLICY.md` — project-level policy adopting `tape-only` convention.
- `.factory/policies.yaml` **POL-004 `no-binary-demo-artifacts`** (MED) — governance-registry entry recording the project's stance.
- Purge PR [`ArcavenAE/switchboard-blue#82`](https://github.com/ArcavenAE/switchboard-blue/pull/82) deleting 62 tracked binaries.

## Duplicate search

Not a duplicate. Distinct from #487 (smoke-before-green gate — behavioral regression gate, not artifact format). Related agent surface only: `agents/demo-recorder.md`.

## Cross-references

- Follows batch 31 post-SHIPPED steady-state gap audit (issues #487, #488, #489, #491, #493, #495 filed 2026-07-04 from switchboard-blue).
- Related agent: `vsdd-factory:demo-recorder`.
- Related orchestrator surface: `orchestrator/per-story-delivery.md` §Step 5.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.