video_editing_poc/.claude/skills/video-editing-external-positioning/SKILL.md

---
name: video-editing-external-positioning
description: Load this skill when drafting or reviewing public claims, release notes, papers, architecture case studies, model cards, benchmark comparisons, production-readiness statements, Fortune 500 reference-architecture assessments, or claims that this video-editing service is cinematic, local, offline, secure, scalable, reproducible, or state of the art. Use it to assemble the evidence package and prevent repository capabilities from being overstated.
---

# Position This Project Externally

## Purpose

Turn repository facts into claims that an independent reviewer can reproduce. Treat code,
plans, tests, executed measurements, and accepted claims as different evidence levels.

Use the repository state and rules dated **2026-07-21**:

- The target is a production-grade reference architecture suitable for a Fortune 500
  engineering organization.
- The hardest live problem is identifying highlights and editing them to high cinematic
  quality with production-ready visuals, sound, music, and voiceover using models packaged
  inside the service runtime.
- Automatic dependency or model downloads, external AI services, unlicensed assets,
  placeholder silence or tones, unapproved rendering, network access, and changes to
  production-facing defaults are prohibited.
- Required environments are macOS development, Linux/VPS production, and cloud
  infrastructure.

Do not weaken these rules to make a release or paper easier to announce.

## When Not To Use This Skill

| Need | Load this sibling instead |
|---|---|
| Classify, gate, or approve a code/config change | `video-editing-change-control` |
| Decide whether tests and measurements meet acceptance thresholds | `video-editing-validation-and-qa` |
| Turn a hypothesis into an experiment and survive adversarial review | `video-editing-research-methodology` |
| Plan work on cinematic highlight quality | `video-editing-cinematic-highlights-campaign` |
| Document build prerequisites or reproduce the runtime | `video-editing-build-and-env` |
| Maintain repository documentation rather than external claims | `video-editing-docs-and-writing` |

Do not use this skill to approve a claim about your own change. Require an independent
reviewer and the gates below.

**SBOM** means Software Bill of Materials.

## Define The Claim Vocabulary

Use these terms consistently:

| Term | Meaning here |
|---|---|
| Technique | A known engineering method used by the repository, such as FFmpeg filtering, Flyway migrations, ports/adapters, or Micrometer metrics. Its presence is not novelty. |
| Capability | Behavior demonstrated by code plus an executable test or retained run artifact for a named commit and environment. |
| Candidate | A plausible design, result, or novelty that has not met its evidence gate. |
| Claim | A bounded statement with named scope, baseline, metric, threshold, commit, environment, and evidence owner. |
| Evidence package | Immutable inputs, commands, outputs, measurements, provenance, negative results, and independent review needed to audit a claim. |
| Production-ready | Verified against the entire production definition of done, not merely able to start or render an MP4. |
| Local | Computation executes on the declared host or contained runtime. This does not imply offline, bundled models, no telemetry, or no download. |
| Offline | A clean, isolated run completes with egress denied and all dependencies, weights, and assets supplied by an approved artifact. |
| Reproducible | An independent operator can recreate a declared result from an immutable revision and artifact set within stated tolerances. Do not imply byte-for-byte identity unless tested. |
| Cinematic quality | A preregistered technical and blinded-human evaluation passes. File validity or the presence of effects is insufficient. |
| State of the art (SOTA) | A statistically defensible improvement over current, relevant external baselines established from approved primary evidence. |

## Start From The Current Claim Ledger

Treat this table as the default posture until newer retained evidence replaces it.

| Area | Repository fact | Allowed wording | Forbidden inference |
|---|---|---|---|
| Platform | `pom.xml` declares Java 21, Spring Boot 3.3.2, Maven, PostgreSQL, Flyway, S3, Actuator, Prometheus, H2, and test dependencies. | "The repository currently declares ..." | "Latest," "supported," "locked," "hardened," or "vulnerability-free." No approved current external version/vulnerability evidence exists. |
| Editing | Code contains source analysis, candidate/director flow, FFmpeg renderers, local asset integration, manifests, and QA report types. | "Implements an in-repository cinematic highlight pipeline candidate." | "Produces production-ready cinematic edits." |
| Visual models | A local HTTP CV adapter and worker exist; configuration defaults to `local-cv` and permits heuristic fallback. | "Supports a local CV worker adapter with configurable heuristic fallback." | "All highlight decisions are model-driven," "fully local," or "offline." |
| Audio models | `tools/local_asset_worker.py` invokes Piper when configured and AudioCraft model loaders for music/SFX. | "Contains adapters for local TTS and generative audio runtimes." | "Models reside in the service runtime," "no downloads," or "production voice/music/SFX." |
| Fallbacks | Historical output may contain silence, tones, or host speech. The 2026-07-21 working tree removes those success paths and rejects missing requested assets. | Identify the exact source revision and asset provenance. | Any cinematic or real-asset claim for an older output or an output without model/asset manifests. |
| Downloads | Worker bootstrap scripts run unpinned `pip install`; model APIs can resolve named weights. Local CV documentation says startup may download dependencies/YOLO weights. | "Current bootstrap paths may access package/model networks." | "Hermetic," "offline," "dependency-locked," or "no automatic downloads." |
| Approval | Highlight rendering now defaults off and approval on; the separate local-director profile also requires a flag. The REST edit-render endpoint and bare flag design still lack production authorization. | State the exact workflow, effective configuration, and approval limitation. | "All rendering requires authenticated, digest-bound human approval." |
| QA | `HighlightFfmpegRenderer.buildQaReport` now probes duration, black ranges, long silence, and sample peaks; asset/mastering and overlay checks remain structural or plan-level. | "Writes a technical QA report with measured defect probes and structural checks." | "QA-certified," "validated loudness," "raster-safe overlays," or "measured cinematic quality." |
| Tests | The suite contains unit, Spring, and FFmpeg-backed tests. A 2026-07-21 offline working-tree `mvn -q -o verify` run passed 245 tests in 62 test classes. | State the command, tree state, date, and attached report. | "Clean-checkout reproducible," "network-isolated," or cross-platform. An earlier clean archived checkout failed because an asset-generation test depended on untracked runtime state or an audible TTS fallback. |
| Operations | Plans, benchmark harnesses, runbooks, alerts, and a Grafana dashboard exist. `docs/load-test-signoff.md` explicitly says execution evidence is pending. | "Operational planning artifacts exist." | "Load-tested," "cloud-ready," "operationally signed off," or "scalable." |
| Enterprise controls | No checked-in CI definition, Maven wrapper, container/deployment manifest, OpenAPI document, architecture-boundary gate, Testcontainers setup, SBOM/signing gate, Spring Security dependency, or threat model was found in Phase 1. | List each as a current gap. | "Secure," "Fortune 500 reference architecture," "cloud-native," or "release governed." |
| Licensing | Asset lookup can copy adjacent `.license.txt` files, but the repository has no complete model/asset/license inventory. | "Supports an adjacent license-file convention for selected assets." | "All assets/models are licensed" or "commercially usable." |
| Novelty | The repository combines known local analysis, planning, asset, and FFmpeg techniques around filesystem project contracts. | "Repository-specific integration candidate." | "Novel architecture," "research contribution," or "SOTA." No novelty search or external comparison is approved. |

Plans and checked boxes prove intent or implementation bookkeeping only. They do not replace
executed evidence. Generated files under `target/`, `input/`, `output/`, or local virtual
environments are not certified evidence unless an evidence manifest names and hashes them.

## Apply The Claim Ladder

Promote wording one level at a time. Never skip a level.

| Level | Required support | Permitted verbs |
|---|---|---|
| 0: Intended | Plan or prompt only | "plans," "targets," "proposes" |
| 1: Implemented | Reviewed code at an immutable commit | "contains," "implements," "configures" |
| 2: Tested | Deterministic automated test passes from a controlled checkout | "tests demonstrate," with scope |
| 3: Measured | Retained representative artifacts and preregistered metrics pass | "measured," with numbers and uncertainty |
| 4: Independently reproduced | Separate reviewer/environment recreates the result | "reproduced on ..." |
| 5: Production qualified | Every applicable enterprise gate passes and operations approve | "production-qualified for [declared scope]" |

Reject adjectives without a level and scope. Replace "fast" with throughput/latency under a
named workload; replace "high quality" with rubric scores and confidence intervals; replace
"secure" with the verified control set and unresolved risk count.

## Gate High-Risk Claims

Build the evidence listed below before using the claim in a paper, release, presentation, or
README. A result can satisfy one row without satisfying another.

| Claim | Minimum evidence package |
|---|---|
| **Production-ready output** | Immutable source rights; no placeholder assets; model/asset provenance; approved director plan; measured media QA; blinded human review; failure/recovery results; retained final, manifest, logs, config, and checksums. |
| **Cinematic quality** | Preregistered category-balanced dataset; baseline outputs; randomized blinded review by declared reviewers; shot relevance, narrative coherence, pacing, visual finish, speech intelligibility, music/SFX fit, mix quality, and overall preference metrics; inter-rater agreement; confidence intervals; failure examples; technical QA. |
| **Local models in runtime** | Image/package inventory; exact model IDs, weight hashes, licenses, paths, memory/accelerator needs; startup/run traces showing local processes; egress-denied success; no host-only fallback; no runtime installation or model resolution. |
| **Offline** | Clean environment with network namespace/egress deny; preloaded approved bundle; packet/connection evidence; cold-start plus full source-to-final run; proof that caches were not inherited; failure if an undeclared artifact is removed. |
| **Licensed assets** | Source, owner, SPDX or verbatim license, commercial/derivative rights, territory/expiry if applicable, file hash, attribution obligation, and approval for every source, font, LUT, music, SFX, voice, model code, and weight. Generated output also requires model/weight/output-use analysis. |
| **Secure** | Threat model; authentication/authorization tests; OWASP ASVS 5.0 scope and evidence; secret/static/dependency/container scans; zero unresolved critical/high findings or recorded risk acceptance; least-privilege runtime; data/log redaction; audit evidence; secured actuator surface. |
| **Scalable** | Documented representative workload and hardware; p50/p95/p99, throughput, error rate, CPU, memory, GC, disk, threads, pools, queue age, and model saturation; 60-minute endurance; 2x peak; slowed-dependency test; horizontal-scale evidence; bottleneck and capacity limits. Do not inherit the user's example API numbers without adapting them to media workloads. |
| **Reproducible** | Clean checkout; one documented command; locked Java/Maven/Python/native/model inputs; checksums; no network for model/media work; macOS and Linux/VPS runs; one platform-neutral application artifact plus signed target-specific runtime/model/image bundles promoted without rebuild; deterministic seeds where applicable; declared numeric/media tolerance; independent reproduction. |
| **SOTA** | Approved primary-source review with dated search protocol; strongest relevant public baseline reproduced or obtained from auditable artifacts; same rights-cleared dataset and budget; preregistered metrics; uncertainty/significance; ablations; negative results; external review. |
| **Fortune 500 reference architecture** | Entire definition of done passes. Score all 15 human-review categories 0-4 with concrete evidence: architecture, domain, maintainability, security, testing, API, data, resilience, observability, performance, cloud operation, CI/CD, developer experience, documentation, and operations. No score below 3; average at least 3.5; security, data, testing, and operations each at least 3. |

For the Fortune 500 claim, also require clean build/run, architecture gates, API contract,
database migration from empty PostgreSQL, logs/metrics/traces/health/dashboards, load and
resilience results, secure container evidence, deployment and rollback exercises, ADRs, and
zero critical behavior dependent on undocumented assumptions.

## Build A Defensible Cinematic Comparison

Do not choose only flattering footage. Freeze the evaluation before rendering.

1. Define intended users, distribution format, input constraints, output duration, content
   categories, hardware budget, latency budget, and prohibited content.
2. Create a rights-cleared, immutable, checksum-indexed dataset covering family, food, car,
   generic, low light, sparse events, noisy audio, no audio, long takes, and failure cases.
3. Freeze these internal baselines where applicable:
   - Source excerpt or uniform-window selection: measures whether highlight identification adds value.
   - Heuristic visual provider: measures the local CV model's contribution.
   - Deterministic plan: measures the director's contribution.
   - Source-audio-only render: measures generated or licensed audio assets.
   - Historical `5d889b0` ("working version but not cinematic"): use only after its runtime and
     exact outputs are reproducibly reconstructed.
4. Add an external baseline only after approved primary evidence and artifacts are vendored or
   cited. Network access is prohibited during this workflow; do not rely on memory for current
   products, versions, papers, benchmarks, or licenses.
5. Match source clips, output duration, compute budget, allowed assets, and human-review process.
6. Preregister metrics, thresholds, exclusions, stopping rule, statistical method, and all
   hypotheses. Predict expected numbers before execution under
   `video-editing-research-methodology`.
7. Randomize and blind human review. Hide system names, filenames, and render order. Retain raw
   scores and rejected samples.
8. Run ablations: remove local CV, director, generated music, SFX, voiceover, and each visual
   treatment separately. Require one mechanism to explain positive and negative observations.
9. Report distributions and confidence intervals, not only averages or a montage of best cases.
10. Send the result through `video-editing-validation-and-qa`, then change control, before
    promotion.

No cinematic acceptance threshold is currently agreed or evidenced. Keep the claim at
"candidate" until the campaign establishes thresholds and passes them.

## Record Artifact, Model, And License Provenance

Create one immutable manifest per evidence package. Store it in the approved evidence location
defined by change control; do not silently add repository paths from this skill.

```yaml
claim_id: <stable-id>
claim_text: <bounded proposed wording>
claim_level: <0-5>
commit: <40-character-sha>
created_utc: <timestamp>
owner: <team-or-role>
independent_reviewer: <team-or-role>
environments:
  - os: <macOS-or-Linux-distribution-and-version>
    architecture: <arm64-or-amd64>
    cpu: <model-and-count>
    memory_bytes: <integer>
    accelerator: <model-driver-runtime-or-none>
commands:
  - <exact-command>
network_policy: <egress-denied-evidence-reference>
inputs:
  - path: <logical-artifact-name>
    sha256: <hex>
    source: <approved-origin>
    license: <SPDX-or-verbatim-reference>
models:
  - id: <model-and-revision>
    weights_sha256: <hex>
    code_license: <reference>
    weights_license: <reference>
    output_use_review: <approval-reference>
outputs:
  - path: <logical-artifact-name>
    sha256: <hex>
metrics: <raw-and-summary-result-reference>
negative_results: <retained-result-reference>
limitations: <known-boundaries>
decision: <rejected-candidate-or-approved>
```

Reject provenance that says only "local," "open source," "free," or a mutable model alias. A
cache hit is not proof that a model is bundled, approved, or available on a clean machine.

## Prove Cross-Environment Reproducibility

Use the same immutable application and model/asset bundle in all environments.

| Environment | Required proof |
|---|---|
| macOS development | Clean checkout; documented toolchain; no IDE dependency; egress denied; cold cache; source-to-final workflow; test and artifact logs. Record Apple/Intel architecture. |
| Linux/VPS production | Non-root runtime; explicit CPU/RAM/GPU/disk; egress denied; read-only filesystem except declared work volumes; signal/shutdown behavior; cold start; repeated render; recovery after restart. |
| Cloud | Same release artifact; externalized configuration/secrets; least privilege; readiness/liveness; resource limits; telemetry; rolling deploy and rollback; dependency outage and scale tests; no environment rebuild. |

Define reproducibility tolerance before execution. For media output, compare timeline decisions,
streams/codecs, duration, frames or perceptual hashes, loudness, clipping/silence, and human
scores as appropriate. Never promise byte identity across FFmpeg, codec, CPU, or accelerator
variants without proving it.

## Review Every Claim

Copy this checklist into the claim review:

- [ ] Quote the exact proposed sentence and intended audience.
- [ ] Bound the workflow, environment, content categories, commit, and date.
- [ ] Assign a claim-ladder level and an evidence owner.
- [ ] Separate repository facts, measurements, interpretations, and candidates.
- [ ] Name the fairest baseline and equalize inputs, compute, time, and rights.
- [ ] Preregister metrics, thresholds, hypotheses, exclusions, and stopping rules.
- [ ] Attach exact commands, raw logs, configs, immutable inputs/outputs, and SHA-256 hashes.
- [ ] Inventory every dependency, binary, model, weight, font, LUT, source, music, SFX, and voice license.
- [ ] Prove no automatic download, external service, network access, placeholder, or unapproved render occurred.
- [ ] Include negative results, known failure cases, uncertainty, and scope limits.
- [ ] Reproduce on every environment named by the claim.
- [ ] Obtain independent factual, security/license, validation, and change-control approval.
- [ ] Make release wording no stronger than the weakest required evidence item.

Reject the claim if any required box is unknown. "Unknown" is a result, not permission to infer.

## Write Release Notes Without Oversell

Use this template:

```markdown
## <Release or experiment name>

Revision: `<commit>`
Status: <experimental | candidate | qualified for bounded scope>

### Changed
- <observable behavior, not aspiration>

### Verified
- <command, environment, dataset, measured result, threshold, evidence ID>

### Not verified
- <production, security, scale, offline, license, quality, or platform gaps>

### Models and assets
- <immutable IDs/hashes, licenses, approval, whether bundled>

### Compatibility and operations
- <configuration/API/data change, rollout, observability, rollback>

### Negative results and limitations
- <failures, excluded cases, uncertainty, known weak points>

### Claim decision
- Proposed wording: <exact sentence>
- Evidence level: <0-5>
- Reviewers: <roles>
- Decision: <rejected | candidate | approved for exact scope>
```

Do not describe a plan, prompt, unchecked runtime path, synthetic fixture, or mocked test as an
end-user result. Link a release to retained evidence, not to a moving working directory.

## Route Claim Promotion

1. Open the candidate under `video-editing-research-methodology` when the claim depends on a
   quality, novelty, mechanism, or comparative result.
2. Classify the implementation and any production-default impact under
   `video-editing-change-control`. Never change defaults to make an evaluation pass.
3. Generate the complete evidence package without network access or prohibited fallbacks.
4. Ask `video-editing-validation-and-qa` for threshold and evidence review.
5. Assign an adversarial reviewer to reproduce the result and seek counterexamples.
6. Run security/license review for any public, customer, or commercial use.
7. Approve only the exact bounded wording. Record rejected wording and the reason.
8. Publish limitations and negative results beside the claim.
9. Reopen the claim when dependencies, models, datasets, runtime environments, defaults, or
   relevant external baselines change.

## Provenance and maintenance

This skill was grounded on repository revision `97ba827d507292e38387c188a4b88157fd119ddb`
and the project owner's criteria on **2026-07-21**. Primary repository evidence included
`pom.xml`, `src/main/resources/application.yml`, local worker scripts, editing/rendering code,
tests, operational documents, highlight plans/checklists, and Git history. No network research
was performed; current external SOTA, version support, vulnerabilities, and licenses remain
unverified.

Re-verify volatile facts before every claim review:

```bash
git rev-parse HEAD
sed -n '1,260p' pom.xml
sed -n '1,180p' src/main/resources/application.yml
rg -n "pip install|get_pretrained|write_silence|fallback_tone|fallbackTone|writeSilence" tools src/main/java/org/example/videoclips/editing
rg -n "buildQaReport|new RenderQaCheck" src/main/java/org/example/videoclips/editing
find . -maxdepth 3 -type f \( -name 'mvnw*' -o -iname '*docker*' -o -iname '*compose*' -o -iname '*openapi*' -o -iname '*sbom*' \) -print
find . -maxdepth 3 -type f \( -path './.github/*' -o -name '.gitlab-ci.yml' -o -name 'Jenkinsfile' \) -print
rg -n "spring-security|SecurityFilterChain|ArchUnit|Modulith|Testcontainers|CycloneDX|dependency-check|OpenTelemetry" pom.xml src
sed -n '120,190p' docs/load-test-signoff.md
git log --oneline --all --decorate -80
```

Run build, media, security, load, offline, and cross-platform commands only through their
sibling runbooks. Retain their logs and hashes; a command printed here is not evidence that it
passed.