Add AGENTS.md (any-AI entry point) + Gate-B review scorecard
- AGENTS.md: portable onboarding for any assistant (Codex/Claude/etc.) at the repo root -- what the project is, read-order, build/test/run, hard constraints, honest status, env gotchas. Makes the whole repo usable by any AI, not just Claude. - docs/gate-b-review-bowling.md: the production-readiness scorecard. Gate A (technical) measured = PASS; Gate B (human creative rubric) = PENDING. Output is production-ready only when BOTH pass; this is the artifact a human fills to decide. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MPuJXQyAeWpFcTtcnxo1UN
This commit is contained in:
JSLMPR
parent
7012daa6b6
commit
b455a11d82
|
|
@ -0,0 +1,60 @@
|
|||
# AGENTS.md — onboarding for any AI assistant (Codex, Claude, etc.)
|
||||
|
||||
This file is the portable entry point for any AI or human working on this repo. Everything below is plain
|
||||
Markdown/Python in the repo — nothing depends on a specific assistant. (Claude Code additionally auto-loads
|
||||
`.claude/skills` + `.claude/memory`, but those are just Markdown you can read directly.)
|
||||
|
||||
## What this project is
|
||||
|
||||
A **local, offline** service that turns one source video into a cinematic highlight: it selects the moment,
|
||||
auto-directs a story-structured montage, generates music/SFX/voiceover with local models, renders with a
|
||||
cinematic grade, and masters the audio. No external AI services, no runtime downloads. Java 21 / Spring Boot.
|
||||
|
||||
## Read these first (source of truth, in order)
|
||||
|
||||
1. [`README.md`](README.md) — overview, quality rules, models/licenses, limitations.
|
||||
2. [`docs/cinematic-quality-rules.md`](docs/cinematic-quality-rules.md) — the R1–R9 source-adaptive rendering/director rules (all implemented).
|
||||
3. [`docs/RUNBOOK-highlight-e2e.md`](docs/RUNBOOK-highlight-e2e.md) — exact commands: source → rendered `final.mp4`.
|
||||
4. [`docs/LOCAL-MODELS.md`](docs/LOCAL-MODELS.md) — local model runtime + version traps (Intel-Mac reference).
|
||||
5. [`docs/cinematic-highlight-poc-plan.md`](docs/cinematic-highlight-poc-plan.md) — milestone log / roadmap.
|
||||
6. `.claude/memory/ai-handover.md` — latest state, full commit list, honest status. **Always `git log`/`git status` first** — the repo is the live truth.
|
||||
|
||||
## Build / test / run
|
||||
|
||||
```bash
|
||||
./mvnw -B verify # build + all tests + coverage (needs JDK 21 and ffmpeg/ffprobe on PATH)
|
||||
```
|
||||
|
||||
Run the highlight pipeline via the `localpoc` profile — see the runbook (step-by-step). Key entry code:
|
||||
`src/main/java/org/example/videoclips/editing/` (`HighlightSourceScheduler`, `HighlightMontageDirector` =
|
||||
Tier-1 director, `HighlightVisionDirector` = Tier-2 VLM director, `HighlightFfmpegRenderer`). Local model
|
||||
workers: `tools/local_asset_worker.py`, `tools/vision_caption.py`.
|
||||
|
||||
## Hard constraints (do not violate)
|
||||
|
||||
- No automatic dependency/model downloads at runtime; models load offline from `models/` + the local cache.
|
||||
- No external AI services in the media path.
|
||||
- No unlicensed assets; no placeholder silence/tones passed off as generated audio (fail closed instead).
|
||||
- No rendering without an explicit approval flag.
|
||||
- Do not run `tools/run_local_*_worker.sh` in a certified environment (their `auto` modes install/download).
|
||||
|
||||
## Honest status (do not overclaim)
|
||||
|
||||
- Cinematic quality ruleset **R1–R9 complete**; `mvn verify` green (271 tests). Production hardening **started**
|
||||
(CI, README, render-approval gate, Dockerfile, Maven Wrapper).
|
||||
- The video output is a **technically-clean cinematic draft, NOT certified production-ready.** Blockers: no
|
||||
blinded human creative review (Gate B) has passed; source is 576p; music is generic `musicgen-small`; audio
|
||||
models are **CC-BY-NC** (non-commercial). A passing test / valid MP4 is **not** proof of cinematic quality.
|
||||
|
||||
## Environment gotcha (2026-07-24)
|
||||
|
||||
If the app dies with `Operation not permitted` on a socket bind or `/var/folders/.../T`, the sandbox
|
||||
restricted the default `$TMPDIR`/network: run the app JVM with
|
||||
`-Dspring-boot.run.jvmArguments="-Djava.io.tmpdir=<writable>"` and Maven with
|
||||
`-DargLine="-Djava.io.tmpdir=<writable>"`. HF downloads: `export HF_HUB_DISABLE_XET=1`.
|
||||
|
||||
## Conventions
|
||||
|
||||
Small, reviewable, test-backed commits. Follow existing patterns. Don't change production-facing defaults
|
||||
without noting old→new value and rationale. Don't commit generated media/models (`.gitignore` / `.dockerignore`
|
||||
already exclude `output/`, `input/`, `models/`, `.venv-*`).
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
# Gate-B review — bowling highlight (production-readiness scorecard)
|
||||
|
||||
Sample: `output/localpoc/highlight-projects/bowling_strike/final.mp4` (auto-directed, R1–R9 pipeline).
|
||||
This is the artifact that answers **"is the output production-ready?"** — it is production-ready only when
|
||||
BOTH gates below pass. Fill Gate B by watching/listening; do not relax thresholds to make it pass.
|
||||
|
||||
## Gate A — technical (objective, measured 2026-07-24) → **PASS**
|
||||
|
||||
| Check | Threshold | Measured | Pass |
|
||||
|---|---|---|---|
|
||||
| Container / video codec | MP4 / H.264 | mp4 / h264 | ✅ |
|
||||
| Audio codec / sample rate | AAC / 48 kHz | aac / 48000 (stereo) | ✅ |
|
||||
| Resolution (portrait source) | portrait, no distortion | 1080×1920 | ✅ |
|
||||
| Frame rate | 30 fps | 30/1 | ✅ |
|
||||
| Integrated loudness | −16 LUFS ±1 | −16.1 LUFS | ✅ |
|
||||
| True peak | ≤ −1.5 dBTP | −2.8 dBFS | ✅ |
|
||||
| Black / long-silence (unintended) | none | none detected | ✅ |
|
||||
| Audio present through end (no early cutoff) | audio ≈ video length | 9.8 s audio / 9.67 s video | ✅ |
|
||||
|
||||
## Gate B — human creative (blinded, subjective) → **PENDING**
|
||||
|
||||
Score each 0–4 (0 unusable · 2 acceptable · 3 good · 4 excellent). **Pass = average ≥ 3.5, every dimension ≥ 3,
|
||||
factual errors = 0, and preference over the deterministic baseline > 50%.** At least 3 reviewers; randomize A/B
|
||||
order; keep disagreements.
|
||||
|
||||
| Dimension | What to judge | Score (0–4) | Notes |
|
||||
|---|---|---|---|
|
||||
| Highlight selection | Is the *right* moment chosen, with good in/out points? | ☐ | |
|
||||
| Story / structure | Clear build → payoff; nothing feels arbitrary or missing | ☐ | |
|
||||
| Pacing & transitions | Cut lengths, slow-mo ease, dissolves feel intentional | ☐ | |
|
||||
| Visual craft | Framing, push-in, grade, exposure, overlay | ☐ | |
|
||||
| Sound design | Music fit + build, SFX, source-under-score balance | ☐ | |
|
||||
| Voiceover (if any) | Intelligibility, timing, script faithfulness | ☐ N/A | none in this cut |
|
||||
| Factual grounding | Overlay/narration assert only what's on screen | ☐ | |
|
||||
| **Preference vs baseline** | Prefer this over the plain deterministic cut? (Y/N per reviewer) | ☐ | |
|
||||
|
||||
Reviewers: __________ Date: __________
|
||||
Average: ____ Min dimension: ____ Factual errors: ____ Preference >50%: ____
|
||||
|
||||
## Verdict
|
||||
|
||||
- **Gate A:** PASS (measured above).
|
||||
- **Gate B:** PENDING a human review — until it passes, the output is a technically-clean cinematic **draft**,
|
||||
**not** production-ready.
|
||||
- Independent of the gates, commercial release is additionally blocked by model licensing (MusicGen/AudioLDM2
|
||||
are CC-BY-NC) and the 576p source ceiling — see [`README.md`](README.md) Limitations.
|
||||
Loading…
Reference in New Issue