# Levchyk — new-project implementation brief

Owner decisions: 7 September 2026. Start page: https://levchyk-project-start.pages.dev/
This document replaces the earlier discussion recommendations where they differ.

Companion files (download with this brief):
- https://levchyk-project-start.pages.dev/REUSE_MAP.json
- https://levchyk-project-start.pages.dev/GOLDEN_REFERENCES.json
- https://levchyk-project-start.pages.dev/NEW_PROJECT_AGENTS.md
- https://levchyk-project-start.pages.dev/levchyk-project-bootstrap.zip

Build a NEW, clean repository for sung character ads. Reuse the inspected implementation
parts in REUSE_MAP.json. Do not rebuild working media plumbing and do not fork the entire
old factory. The old project is a read-only donor, not the runtime of the new app.

This brief authorizes the project design and implementation direction. It does not supply
provider credentials, a per-film spending budget, or authorization to buy the first film.
Before paid production, use the owner's recorded run brief and budget. Do not repeatedly
ask for intermediate creative approval within that authority: the owner reviews the final film.

## 1. The product we are building

One trend opens into its source video, its reverse-engineered flow, and adaptations for our
product, geography, angle and passports. The reusable asset is a VERSIONED FORMAT, not a
finished GoPure film and not a universal story template.

The model is:

    10/10 reference library → reusable format
    new trend → matching format version, with match evidence
    format + trend + angle + product + geo + passports → adaptation run → final film

Borrow the source's music, vocal delivery, visual finish, acting, pacing, camera language,
caption language and story mechanics as closely as practical. Adapt the people, product,
problem, supported endpoint, wording, offer and geography. Preserve the format's recognizable
style while allowing other angles and products. Reusing a format does not force every story
to use the same names, number of characters, genre, fixed beats or source timestamps.

For a new similar trend, compare its actual evidence with candidate formats. Store the
matching reasons, differences and selected format version. A real mismatch stays unclassified
or creates an explicitly named new format; never quietly force it into the nearest template.

## 2. Owner decisions to implement

- First format: sung character ads. Suno produces the integrated vocal and music track.
- Music route: use what works best for the reference. Persona is optional. Compare explicit
  supported routes and select before generation. Best means reference fit and clear localized
  words first, then time and cost within budget. Do not invent Persona success or silently
  swap a failed provider, model, source or operation. An intentional route change is a new
  recorded operation with its reason, source lineage and budget; the old failure stays failed.
- Fidelity: borrow the style of everything as much as possible, adapted to our product and passports.
- Reuse: the reverse-engineered format must accept other angles and other products.
- Owner review: final film only, within the recorded brief and budget. Audio, boards and
  clips still receive internal acceptance before dependent work; these are not owner checkpoints.
- Iteration: keep revising; after MORE THAN FOUR failures on the same eligible creative
  criterion, loosen that parameter transparently using the policy below.
- Product result: a clear endpoint bounded by product evidence.
- Interface: retain the familiar trend → reverse-engineered flow → adaptation experience.

## 3. Our 10/10 creative references

The exact folder is `data/music_dna_raw`, not `music_data_raw`.
The five owner-loved originals are:

- `targ.mp4`
- `krov.mp4`
- `svekr.mp4`
- `sisterbrazil.mp4`
- `media-922fbf8f0e9c.mp4`

All five were present and SHA-256 verified during preparation. See GOLDEN_REFERENCES.json
for each original path, destination, duration and hash. On the current host they live at
`/workspaces/UGS/LevchykUGS/data/music_dna_raw/`. Read or copy them; never modify the donor files.
Import exact bytes into `references/music_dna_raw/` or content-addressed media storage,
verify the manifest hashes, and retain the originals. The public bootstrap ZIP contains
instructions and manifests, NOT these videos or the private donor source code.

The 10/10 rating is the OWNER'S creative taste. Treat the original music, animation, acting,
storytelling and pacing as the examples to emulate. Automated reviewers should calibrate
to them, not punish them for failing a generic songwriting or cinematic rubric. Select the
closest reference for the current format; do not average all five into one voice or genre.
Reference praise is not medical evidence, permission to copy unsupported claims, or proof
that every reference shares one exact BPM, key, plot, shot count or repeated chorus.

Reuse `hookd/music-dna/corpus.json`, existing source notes and the three creative skills
listed in the reuse map. After the format blueprint, read Music DNA and its three references,
then the product-state passport and contract, then facial-performance and its evidence,
contract and revision loop. Verify reused analysis against the exact reference hash.
Missing or changed required originals stop that import; no substituted references.

## 4. Copy and reuse, with traceable origins

Donor repository: https://github.com/PytaichukBohdan/LevchykUGS

Pinned snapshots:

- Stable completed-film base: `5edbbca04c3febe3d9c68b01bc9639da10f1851b`
- Suno/audio improvements from 4d3bc1a052: `46349e4292326c7076f1f90447f48aade26cb455`
- Persona adapter from 4ae2edc324: `255e2bcc40323656cd8d7e84022b51b9349eaf32`

Use REUSE_MAP.json as the file-level porting map. Every entry names its commit, exact path,
SHA-256, target responsibility and integration caveats. GitHub links may require repository
access. The map is not a claim that these files form a standalone runnable dependency closure.

COPY: small modules, tests, creative references and contracts that retain their behavior.
EXTRACT: working functions from modules coupled to the old Factory, rewiring their real
imports, paths and storage boundaries. REFERENCE: worked formats and product examples;
copy their structure, then replace their actual product/cast/geo data.

Specific starting points:

1. `hookd/studio/app.js`: reuse renderWorld, buildProgramHtml and renderFactory interaction
   patterns; `index.html`, `styles.css`, `build_studio.py` and `catalog_views.py` show their
   projection contract. Expose format versions and new adaptation controls in the new app.
2. `hookd/trends/09-targ-upload/reverse-sequence.json`, `source-fidelity.json` and
   `blueprints/singing-cartoon-vsl/`: reuse mechanisms, evidence and preserve/change structure.
   Replace specific names, products and role-count assumptions with format and run data.
3. Music-worktree `hookd/gen.py`, `audition_song.py`, `finish_song.py`, the two song harness
   contracts and their tests: reuse cover payloads, durable task receipts, take selection,
   lyric coverage and authorized edge edits. Do not reimplement provider behavior from prose.
4. Persona-worktree `hookd/suno_persona.py` and `test_suno_persona.py`: optional adapter.
   The inspected Persona experiment failed; the adapter's presence is not proof of success.
5. `hookd/render.py`, `harness/thumbs.py`, `test_render.py`, `test_video_refs.py`: reuse
   actual reference-video submission, negative prompts, preflight and ledger persistence.
6. `music_dna_audio_identity.py`, `music_dna_reel.py`, `music_dna_research.py`,
   `evaluate_music.py` and their dependencies/tests: reuse complete audio identity,
   actual-listening evidence and distinction between access failure and quality failure.
7. `platform/app/song_captions.py` and its tests: copy the small word/phrase module.
8. `platform/app/worker.py`: extract assemble_video, caption_ass and related helpers.
   Preserve the terminal-frame and cumulative timing fixes; use the worker tests as the
   regression source. `platform/scripts/assemble_variant.py` shows the validated entry path.
9. `harness/problem_passport.py`, `harness/facial_performance.py`, `review_problem.py` and
   their tests: preserve concern ownership, state progression, readable faces and selective
   revisions. Parameterize soft creative gates according to section 6.
10. `platform/app/jobs.py`, `db.py`, `storage.py`, `config.py`, `workspace.py`, relevant
    migrations, `platform/edge/` and `harness/manifest.py`: reuse durable jobs, leases,
    content-addressed storage, exact failure records and accepted-asset invalidation rules.
    Remove Factory-specific stage coupling; do not copy production secrets or live job rows.

Import process:

1. Obtain authenticated read access to the donor repository in a SEPARATE donor checkout.
   Verify each pinned commit exists. Do not check out or modify the main production tree.
2. Read exact blobs with `git show <commit>:<path>` and verify each REUSE_MAP SHA-256.
   For extraction, keep the original snapshot and provenance record until the port is reviewed.
3. Copy each selected unit into the clean repo with its tests and required dependencies.
   Create `REUSE_PROVENANCE.json` mapping old commit/path/hash → new path and modifications.
4. Inspect imports and runtime dependencies, including FFmpeg, caption fonts, gen helpers,
   harness imports, httpx, Postgres and the R2 gateway. Never fake a working import.
5. Port the meaningful regression checks before changing behavior. Current owner policy
   intentionally replaces some historical creative thresholds, but not data-integrity tests.
6. Import and verify the five original videos separately. Read-only historical outcomes
   may be linked as evidence; no old film, approval or paid run becomes a new adaptation.

Do not wholesale cherry-pick active worktree histories, copy hundreds of paid attempts into
the new source tree, use GoPure-specific production scripts as the engine, or create a runtime
dependency on an ephemeral `trees/<session>` directory.

## 5. The minimum new architecture

Use the existing Python + Postgres + R2 foundation, with a small Cloudflare frontend.
This revises the earlier SQLite suggestion: retaining the working persistence/storage
contracts is preferable to building and later migrating another database layer.
Use new deployment bindings and a separate database/bucket namespace; do not point new
jobs at the old project's live queue or mutate its media catalog.

Keep the domain small:

- GoldenReference: original asset, hash, owner rating and observed style evidence.
- FormatVersion: reverse-engineered mechanisms, musical and visual style, roles, adaptable
  slots, source evidence and generation/review policy. Immutable once used by a run.
- Trend: original video, selected format version, match evidence and source-specific differences.
- Product + Geo + PassportSet: facts, permitted claims, exact endpoint, localized offer,
  language, product image, identities, affected characters and staged concern references.
- AdaptationRun: angle, product, geo, passports, format version, route, budget, time/spend and status.
- AssetVersion + Job + Review: requests, task IDs, media hashes, dependencies, rejection
  reasons, criteria version and accepted/published pointers. Reuse proven storage patterns.

Suggested layout:

    web/                   trend library, format flow, adaptation, final review
    app/providers/         extracted Suno, Persona and visual adapters
    app/media/             verified audio, captions and FFmpeg assembly
    app/quality/           internal acceptance + versioned criterion policy
    app/jobs/              existing lease/event/reconciliation patterns
    contracts/             format, passport, run, review policy
    formats/               reusable, versioned reverse-engineered flows
    references/            golden manifest; originals in local/R2 media storage
    tests/                 ported regressions + cross-product format reuse
    REUSE_PROVENANCE.json   where every ported part came from

The new orchestration should be thin. Do not create a coding-agent session for each upload,
poll, caption or encode. Use one planner for the creative plan and feedback-informed repairs;
code performs mechanical steps. Expose errors and state from one authoritative projection.

## 6. The owner's fifth-rejection policy

Implement this explicitly; do not leave a copied 'never lower any threshold' rule to
silently override the owner's new instruction. Freeze each EVALUATION VERSION. Changing
a soft criterion creates a new policy version, not a retroactive edit to a failed receipt.

Count observed quality rejections per asset lineage + criterion + creative intent. A new
take ID or prompt revision does not reset that counter. Provider errors, missing media,
malformed reviews and inability to hear/watch are operation failures; they do not count.

- Failures 1–4: diagnose and author specific corrections, preserving accepted siblings.
- Failure 5 (more than four): loosen the blocking SOFT parameter once, record old/new
  bounds, the five rejection IDs and the rationale, then re-review the best preserved
  candidate under the new version before purchasing another take.
- Implementation default for a 1–5 subjective score: lower that criterion's minimum by
  0.5, with a floor of 3.0. For subjective timing/style-distance tolerance, expand it by
  20%, at most twice from its initial bound. These numeric steps are an implementation
  interpretation, not numbers supplied by the owner. Store them as visible configuration.
- A criterion's next relaxation needs five further observed rejections. Keep the same
  counter history and scope; never repeatedly loosen every category after one failure.
- At the configured floor, keep making targeted creative revisions within the remaining
  budget; reconsider the shot execution or prompt. Do not declare success just to exit.

Eligible examples: exact eyebrow reaction timing, degree of expressive intensity above
readability, minor groove-similarity score or nonessential style-matching precision.

Never relax: product truth or evidence-bounded endpoint, required lyric/story/CTA coverage,
understandable required words, correct identity and concern ownership, actual use and
elapsed story time, observable required faces/states, complete usable media, actual review
access, required provider/input identity, budget limits, or truthful publication state.
If a rubric uses integer scores, a 3.5 threshold still requires a 4; normalize its scale
explicitly or use the next bounded version. Do not pretend a fractional gate changed an
integer review. New reviews state their criteria version and any relaxed parameters.

The 10/10 references stay the creative target. A practical acceptance threshold is not a
new rating of the original, and a relaxed pass is never relabeled as an unchanged strict pass.
Owner-facing final review shows the film, remaining compromises and any criteria adjustments.

## 7. Production and speed

Reference/format → adaptation brief → integrated Suno soundtrack → internal full-song
acceptance → reusable passports/states → reviewed boards → reference-conditioned motion
→ captions/assembly → complete encoded-film review → owner final review.

The owner does not need to approve intermediate stages. The agent continues all authorized
creative revisions. Real source/credential/provider/budget blockers remain explicit failures.
Do not promise a finished film from a task receipt or an opening preview.

Use the already-working full-audio transport and provider preflight. Cache only verified
source analysis or unchanged accepted assets; never use cached work as a failed-run substitute.
Reuse a format without repeating its research. Reuse cast and product states only when they
match the new run's identity, product and endpoint. Run independent ready scenes concurrently
within provider and budget limits, with each scene's review dependencies intact. A bad clip
invalidates that clip and downstream assembly, not its accepted soundtrack or sibling clips.

Measure wall time by stage, first-pass acceptance, paid requests, failed-operation costs,
cost per accepted minute and time spent waiting for review. The previous 45–90 minute target
was a hypothesis, not a production SLA. Establish a baseline with the new reused implementation.

## 8. What the first interface shows

1. Trend library: source, format label/version, classification evidence and available adaptations.
2. Trend detail: source playback and readable reverse-engineered flow; what is fixed,
   what can vary, musical/visual reference choices and relevant 10/10 examples.
3. Recreate panel: product, geo/language, angle, passports, supported endpoint, run budget.
   The selected music route is visible; Persona is not a compulsory blocker.
4. Production: accurate current stage, spend, accepted asset count, failed criterion and
   any policy adjustment. Show latest attempt / latest accepted / published separately.
5. Final review: complete film, source comparison, change summary, remaining compromises,
   version identity and approve / request revision actions. Preview is separately labeled.

## 9. Definition of done for the new project

- The clean repo runs without importing code from the old worktree at runtime.
- Every reused unit has donor provenance, resolved dependencies and relevant tests.
- All five original videos are imported by verified hash and labeled owner-rated 10/10.
- A versioned reverse-engineered format drives an adaptation from product/geo/passport inputs.
- The same format supports a second angle and a second product without changes to engine code.
- A new similar trend can be matched to the format with stored reasons; a mismatch is explicit.
- The fifth-rejection policy is tested at counts 4/5, across take IDs and after its first
  adjustment, including hard-invariant protection and retained rejection history.
- Crash-after-submission, duplicate callbacks, stale approval, source mismatch, failed review
  delivery, accepted-sibling preservation and wrong-final-version publication are tested.
- Once paid production is authorized, one complete sung film passes the declared internal
  gates and is delivered for owner review. Never call the whole product validated from mocks.

Begin with the reuse inventory and verified reference import, then build this vertical
slice. Reuse the wheel; redesign only the workflow that has been slowing it down.