diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c4020b0b..f6f251e5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,11 @@ # Contributing to Maestro +## Development status + +Start with [CURRENT_WORK](docs/development/CURRENT_WORK.md) for integrated work, +active areas and verified pending tasks. Read domain contracts on demand; archived +phase packets and session handoffs are not the current queue. + Thanks for your interest in improving Maestro! This is a local-first AI video/image/music studio built on the [Wan2GP](https://github.com/deepbeepmeep/Wan2GP) pipeline and distributed through [Pinokio](https://pinokio.computer). diff --git a/docs/archive/.ignore b/docs/archive/.ignore new file mode 100644 index 00000000..6d91d9a6 --- /dev/null +++ b/docs/archive/.ignore @@ -0,0 +1,4 @@ +# Historical documents are opt-in for ordinary ripgrep searches. +# Use an explicit file path or rg --no-ignore docs/archive when investigating history. +* +!README.md diff --git a/docs/archive/2026-09-06/architecture-wave/EXECUTION_BASELINE.md b/docs/archive/2026-09-06/architecture-wave/EXECUTION_BASELINE.md new file mode 100644 index 00000000..2e29e982 --- /dev/null +++ b/docs/archive/2026-09-06/architecture-wave/EXECUTION_BASELINE.md @@ -0,0 +1,100 @@ +# Architecture execution baseline + +Status: living register for the 12-phase wave (`fase1.md`–`fase12.md`). +Verified against `origin/main` **`9ac4cacb`** (2026-09-05). + +This document is the single queue for that wave. Working notes under +`comunicaciones/` are historical evidence only. + +## Authority by datum + +| Datum | Authority | Not authority | +|---|---|---| +| Canonical tasks, job events, wait/cancel | `TaskRegistry` / `app/services/task_manager.py` and the durable generation queue | Generation-record JSON, Activity cards, chat prose | +| Story project, cue, song candidate, production | Story library (`.story-library-v1.json`) and Story domain IDs | Titles, `v1` labels, filenames, Wizard in-memory reports | +| Published bytes and provenance | Adjacent `.meta.json` asset-manifest v1 | Generation-record projection, gallery order | +| Generation attempt lifecycle | **Projection** over asset-manifest + provenance + job lifecycle (`generation-record v1`, #138) | A second scheduler, a second media store | + +`GenerationRecord` does not own GPU workers, file bytes or Story candidates. +Writers stay in the existing stores. Wiring into `_launch_runtime.py` is a +later sequential PR (phases 4–5). + +Workspace **collection** (`workspace_id`) is optional. `output_folder` is the +physical directory name. Do not invent a collection to satisfy a schema. + +## Phase graph + +Each arrow requires the **merge** of the source phase into `origin/main`, not +merely an open PR. + +```text +1 → {2, 3} +3 → 4 → 5 +{2, 4} → 6 +{5, 6} → 7 +4 → 8 +5 → 9 +7 → 10 +{6, 7} → 11 +{3, 7} → 12 +``` + +Hotspot rule: at most one open PR may edit `_launch_runtime.py`, `useStore.ts`, +`agentActions.ts`, `StoryLabPanel.tsx`, or Director/Wizard runtime. Branches +start from current `main`; they are not stacked. + +## Delivery matrix + +Columns are independent. Do not infer merge from CI, or CI from a previous +commit's Cursor review. + +| Entrega | Diseñado | Implementado | Commit | PR | CI del head | Cursor del head | Merge | Validación real | SHA | +|---|---|---|---|---|---|---|---|---|---| +| #135 MiniMax-Music3 | sí | sí | sí | #135 | verde al merge | 5 bugs corregidos en el head mezclado | **sí** `a899a8cc` | no (smoke local aparte) | head `93287183` | +| #138 generation-record v1 | sí | sí (proyección) | sí | #138 | verde al merge | 5 bugs corregidos (`b66ea0a9`) | **sí** `3f14b0e0` | no | head `b66ea0a9` | +| #137 lyrics guard | sí | sí (librería) | sí | #137 | verde al merge | alias `startswith` defectuoso quedó en main | **sí** `9ac4cacb` | no | head `8c696b26` | +| #136 docs cola | sí | sí | `b2bdad47` + este commit | #136 | verificar head nuevo | verificar head nuevo | no | N/A | ver PR | +| #139 lyrics alias tokens | sí (F2.3 parcial) | sí (prefijos) | `a6b7b0ff` | #139 | verde | Bugbot SUCCESS | no | no | `a6b7b0ff` | +| #140 Story song pending | sí (cliente) | sí (pending antes de generate) | `dc63eb5b` | #140 | verde en `dc63eb5b` | hallazgos de `5d513534` corregidos en `dc63eb5b`; Bugbot del head nuevo pendiente | no | no | `dc63eb5b` | + +Stashes (do not apply or delete): `stash@{0}` CI e2e on `test/create_e2e_test`; +`stash@{1}` Hunyuan3D/model3d on `feat/3d-compositor-recipe`. + +Cursor opened `origin/cursor/music-recovery-persistence-6c38` (`ae76c653`) +without a PR. #140 already contains the equivalent persist/reattach fix. +Do not land that branch unless a human compares it with `dc63eb5b`. + +## What #135/#137/#138/#139 still leave open + +Verified on `9ac4cacb` plus the open PR heads. Do not copy old Cursor +findings onto a SHA that already fixed them. + +| Source | Already in tree | Still missing | +|---|---|---| +| #135 | Local ACE-Step + MiniMax-Music3, download, 300s clamp, captions, generate without API key | Server-side song attach; lyrics guard not wired; generation-record not wired | +| #137 | Spanish contamination + bounded CJK/Arabic strip; `[Verse]` allowed | Prefix aliases on main (`English`→es, `en español`→en); empty vocal / unevaluable language / Estonian-as-Spanish; destructive repair-by-default; wiring to generate | +| #138 | Portable generation-record projection; cancel/retry/timing mapping | Empty-list patch semantics; write-point CAS; optional workspace collection; no producer wiring | +| #139 | Token aliases longer than 2 letters | Remaining F2 corpus (empty vocal, unsupported language ≠ ok, protected multiline exact, no destructive default) | +| #140 | Pending `song-…` before generate; sidecar recovery; refuse pending staging | Server finalization without browser (phase 5); launch still blocking POST | + +## Next slices (this wave) + +Mapped onto `fase1.md`–`fase12.md`. Do not open a slice whose arrow is not +merged. + +1. **Phase 1 (this PR)** — this baseline. +2. **Phase 2** — continue #139 after phase 1 merges: unevaluable languages, + exact protected spans, no destructive default. +3. **Phase 3** — generation-record authority after phase 1 merges. +4. **Phase 4** — idempotent music submit (minimal `_launch_runtime.py`). +5. **Phase 5** — server-side music finalization (launch sequential after 4). +6. **Phase 6** — music spec/catalog after 2 and 4 merge. +7. **Phase 7** — async client rehydration after 5 and 6. +8. **Phase 8** — Wizard workflow concurrency after 4. +9. **Phase 9** — Story Music router extract after 5. +10. **Phase 10** — Story session controller after 7. +11. **Phase 11** — Studio music `useStore` slice after 6 and 7. +12. **Phase 12** — visible traceability after 3 and 7. + +Real media smoke remains `bash scripts/run_real_media_smoke.sh` with explicit +confirmation. It is never GitHub Actions. diff --git a/docs/archive/2026-09-06/architecture-wave/SLICE_QUEUE.md b/docs/archive/2026-09-06/architecture-wave/SLICE_QUEUE.md new file mode 100644 index 00000000..993a15eb --- /dev/null +++ b/docs/archive/2026-09-06/architecture-wave/SLICE_QUEUE.md @@ -0,0 +1,297 @@ +# Slice queue + +## Current integration base + +New ordinary work branches from `origin/development` and targets `development`. +`main` is reserved for the published Pinokio version. Follow +[BRANCHING.md](../../../development/BRANCHING.md) for releases, hotfixes and transition of existing PRs. +Historical main/merge records below retain their original meaning; do not rewrite +accepted history or infer that a PR is merged from its existence. + +Humans own merges as an operational act; that click is not a technical code +review. Agents own technical review and QA. See +`docs/development/AGENT_QA_POLICY.md`. Agents do not merge until checks are +green, and never open a second PR on the same hotspot. + +PRs should be **medium and cohesive** (about 300–1,000 net lines) with one +verifiable contract. Do not open a PR per property, action or tiny component. + +Canonical sources in git: + +- Domain identities: `docs/development/DOMAIN_MODEL_AND_ASSET_PROVENANCE.md` +- i18n boy scout: `docs/development/INTERNATIONALIZATION.md` +- Architecture contracts: `docs/development/ARCHITECTURE_FOUNDATION.md` +- Independent review/QA: `docs/development/AGENT_QA_POLICY.md` and + `docs/development/QA_ACCEPTANCE.md` +- Execution baseline and 12-phase wave: `docs/development/EXECUTION_BASELINE.md` + and `fase1.md`–`fase12.md` (repo root). Working notes under `comunicaciones/` + are session handoff only. + +Working notes under `comunicaciones/` are session handoff only. They are +gitignored and are not canonical. + +## Landed on main (as of #137) + +`main` points at merge #137 (`9ac4cacb`, 2026-09-05). That commit sits on +#138 (`3f14b0e0`) and #135 (`a899a8cc`). The queue below records what is +present in that tree; the numbered history is kept so earlier slice +decisions are not rewritten. MiniMax-Music3, generation-record v1 and the +lyrics-language library are landed. `_launch_runtime.py`, `useStore.ts` and +`agentActions.ts` are free for **one** sequential PR: durable Story song +identity. + +Asset-manifest v1 writers: Studio generate (simulated, WGP, H3, SFX), Tools +upscale/revoice, Recast/Repaint/Outpaint, MiniMax image, Series assembly, 3D, +Rig, Director H3 join, Director timing attach, alternative songs, scene +recording, Video Editor screenshot/export, comic animatic. + +Sidecar failure: Hunyuan3D and Rig keep the GLB when provenance write fails. + +Domain provenance: `workspace_id` is the collection; `output_folder` is the +physical directory. `GenerationProvenance` / `CommandContext` distinguish +initiator (`origin.actor` / `tool` / `capability`) from provider/model. +Inspector timing reads `queue_ms` / `inference_ms` / `total_ms`. + +Studio+Wizard provenance landed (#95): generation task IDs are assigned before +publish so Wizard→Studio→asset can share one durable identity. + +`useStore` slices (facade kept): theme, settings (includes model-visibility +focus), developerMode, sidebar, retake dialog, Director, gallery/workspace +(#101), and LLM (#107). Slices bind through `bindSlice` without `as never`. +`developerModeSlice` no longer writes `mediaFilter`; the facade still leaves +`auditdev` when developer mode turns off. Gallery/workspace and LLM extraction +are landed; the remaining generation orchestration stays behind the public +facade and must be extracted in cohesive slices. + +Story Lab UI extracts: + +- #88 shared `ReferenceGallery`, `LocationEditor`, `CharacterEditor`, + `BeatEditor`, `storyLabVisuals` / `StoryLabVisualsProvider`; World, + Characters, Relationships and Structure tabs. +- #91 Music, Trailer, Productions and Compact workspace, with `storyLab` EN+ES. +- #97 split those extracted tabs into smaller panels and added the code-health + PR table (`scripts/code_health.py --check --markdown`). +- #98 Overview + generation-agent panel, EN+ES. +- #100 Assets tab extracted with EN/ES. Assets is no longer remaining in + `StoryLabPanel`. +- #103 added `StoryAssemblyTab`, `StoryLabLibraryChrome` and the shared + `storyLabTabs` registry. Assembly and the library header/tab/project-type/ + preparation chrome are no longer pending extractions. + +Visible i18n is catalog-backed in the migrated chrome, with matching EN+ES +keys: foundation, Extra info inspector/dialog, Assets, Story Lab, Series Lab, +Director, Video Editor, workspaces, and the remaining Studio/creative UI +surfaces (#103, #105, #109). #108 also separates UI locale from conversation, +content, spoken and technical-prompt languages; UI locale must not select the +language of authored content or provider prompts. This remains incremental: +user-authored/generated text and untouched debt are not mass-translated. + +Recipe audio duration: generated audio is sized for its consumers (#93). +#21 was the earlier draft of that fix and is closed as superseded. + +Character Kits / Face Rig / cutout dialogue HOWUSEIT: #94 on `main`. #26 was +the older Cursor docs pass and is closed as superseded. + +`--markdown` without `--check` prints **Ratchet not evaluated.** (#99). CI +uses `--check --markdown`. + +### Cross-cutting work landed after #100 + +- **#104 — two-level UI architecture:** task navigation now exposes a + primary category and inner destination, with an explicit **Output folder** + control. The Wizard also has an embedded/sidebar presentation path. +- **#106 — LLM HTTP router:** LLM endpoints moved to `app/routers/llm.py`; + `_launch_runtime.py` keeps the mount and wiring contract. +- **#107 — LLM store slice:** the LLM drawer state and actions live in + `ui/src/stores/llmSlice.ts`; `useStore` remains the compatibility facade. +- **#110 — compositor boot intro:** the intro animation stays on the + compositor, reducing per-frame browser work. +- **#111 — H3 owner handoff:** legacy H3 GPU ownership is stabilized with + scheduler coverage. +- **#112 — Director temporary audio:** transient Director audio slices are + hidden from the user-facing output flow while their jobs run. +- **#113 — Director server audio adoption:** Story audio that the server + already owns is adopted by name with its Workspace/output-folder context; + the browser does not round-trip the bytes before Director analyzes it. +- **#114 — new Story song before videoclip:** a request for a new song creates + a fresh `music_video` Story, writes and generates its vocal cue, then carries + that cue into Director. The reconciler no longer falls back to an unrelated + selected project/song. The `music-video-new` acceptance scenario covers the + identity chain. +- **#115 — media card viewport sizing:** rendered output cards and their + virtualization share a viewport cap, including vertical-resize invalidation, + so cards stay usable inside the feed. + +## Integrated slices (#116–#120) + +All five PRs are merged into `main` and their required CI checks were green at +merge. The merge commits are recorded here so a handoff never confuses a +prepared branch or an in-progress check with an accepted change. + +- **#116 — documentation after #115:** merged as `215ad2a`; refreshed the + queue and Wizard roadmap for the post-#115 state. +- **#117 — Studio configuration slice:** merged as `bfd4e9d`. The typed + `studioConfigurationSlice` owns Studio form/configuration state while + `startGeneration` and Tools execution stay in `useStore`; the public facade + and architecture coverage remain intact. The extraction reduces + `useStore.ts` from 10,239 to 9,741 lines. +- **#118 — Story Lab production controller:** merged as `e545836`. The + `storyProductionController.ts` owns Story Lab → Director production handoff + for film/trailer and music-video flows, including model/reference/audio + preparation. The extraction reduces `StoryLabPanel.tsx` from 4,688 to 4,395 + lines without touching `useStore.ts` or `_launch_runtime.py`. +- **#119 — exact Story song → music-video identity/provenance:** merged as + `4bc7376`, with simulated E2E and Cursor checks green. The opt-in real smoke + generated the requested song and an H264/AAC video of 19.75 seconds. The + harness's initial false negative came from selecting a lateral `Untitled + story` project; exact-title selection is now covered by the accepted flow. +- **#120 — code-quality trend score:** merged as `658a1c3`. The current + aggregate is **48.7/100**: complexity **52.1**, concentration **53.3**, + oversized-file health **28.5**, and modularity **62.2**; this is **+2.2** + against the historical committed baseline. It is a diagnostic trend signal, + not a CI blocker or quality certificate; the existing ratchet remains the + guardrail. CI publishes the score and comparison in PRs. + +## Queue history (original order, statuses updated) + +1. **Domain provenance contract** — landed (#86). +2. **Typed Zustand composition** — landed (#87). +3. **Story Lab simple tabs** — landed (#88). +4. **Story Lab Music + Productions** — landed (#91, split further in #97). +5. **Story Lab Overview** — landed (#98). +6. **Story Lab Assets tab** — landed (#100). +7. **Story Lab assembly + library chrome** — landed (#103), including + `StoryAssemblyTab` and `StoryLabLibraryChrome` with EN/ES. +8. **`useStore` slices** — gallery/workspace landed (#101), Director is + extracted, and the LLM slice landed (#107). Keep the public facade and + extend `architectureSlices.test.mjs`; do not move all of `startGeneration` + in one PR. At most one open PR may touch `useStore.ts`. +9. **Backend by domain** — LLM router landed (#106). Continue with one + complete router + services per PR (Assets, Music, Series, Comics, …), + preserving route-table ordinals. Do not split `_launch_runtime.py` by line + count. +10. **Provenance applied by flow** — Studio+Wizard landed (#95), Story song → + Director was hardened by #112–#114/#119, Series → Comics exact + provenance landed (#124), and generation-record v1 landed as a + portable projection (#138). Remaining identity work is Story music + versions and cue-by-id recovery after the client closes. 3D+Director + already has folder-vs-Workspace provenance (#89). + +## Integrated slices (#121–#134) + +These PRs are merged into `main`. Do not re-plan them. + +- **#121 — documentation after #120:** `0d5b077`. +- **#122 — Wizard conversation `409` recovery:** `98b824a`. Concurrent + conversation writes merge/retry instead of silently overwriting. +- **#123 — semantic song/lyrics language:** `c4e45d2`. Requested lyric + language and quoted spans are preserved; UI locale does not choose content. +- **#124 — Series → Comics exact provenance:** `ecad72d`. Cross-domain + handoff keeps project/production/run/task/output IDs. +- **#125 — remove background Tool:** `020f37e`. +- **#126 — task cost reports:** `08e1adc`. +- **#127 — rich PR template:** `78ed61e`. +- **#129 — Tools image/video upscale:** `df146f2`. +- **#130 — nightly ACE-Step smoke recipe:** `227d0e8`. Uses the local + ACE-Step route, not a MiniMax Music model ID. +- **#131/#132 — local validation vs real smoke:** `94921fb` / `31c0a42`. + `scripts/validate_local.sh` is provider-free; real media is + `scripts/run_real_media_smoke.sh` with explicit confirmation. +- **#133 — Tools upscale worker extract:** `08993d5`. +- **#134 — Wizard workflow persist pinned to source workspace:** `247554a2`. + +## Integrated slices (#135–#137) + +These PRs are merged into `main`. Do not re-plan them. + +- **#135 — local MiniMax-Music3:** `a899a8cc`. ACE-Step and MiniMax-Music3 + are selectable local backends. Wizard download, duration clamp (300s), + caption preservation and local generate-without-API-key landed with the + feature. This was the hotspot PR on `_launch_runtime.py` / `useStore.ts` / + `agentActions.ts`. +- **#138 — generation-record v1:** `3f14b0e0`. Portable projection over + asset-manifest, provenance and job lifecycle. New modules only; wiring + into launch/Activity/Library is still sequential. +- **#137 — lyrics language guard:** `9ac4cacb`. Provider-free Spanish + contamination checks and bounded foreign-script repair. Not yet wired + into write-song/generate. A follow-up must replace prefix aliases + (`English` starts with `es`; `en español` starts with `en`) with exact + aliases plus tokens longer than two letters. + +Open, not landed (verify CI/Cursor on the current head; do not infer merge): + +- **#136 — this PR.** Execution baseline, phase graph and phase files. +- **#139 — lyrics alias tokens** (`a6b7b0ff`). Covers F2.3 prefixes only. +- **#140 — Story pending candidate** (`dc63eb5b`). Client persist-before-generate. + Does not touch `_launch_runtime.py`. Server finalization is phase 5. + +## Next medium PRs after #137 + +Keep these as separate, reviewable slices. Each `faseN.md` is the packet. +Do not open a slice whose graph arrow is not **merged**. + +1. **Phase 1 (this PR)** — execution baseline. Unlock 2 and 3 after merge. +2. **Phase 2** — continue #139: unevaluable languages, exact protected spans, + no destructive default. Library only. +3. **Phase 3** — generation-record authority (projection, CAS, no producers). +4. **Phase 4** — idempotent music submit; sole sequential `_launch_runtime.py` + owner until it merges. +5. **Phase 5** — server-side music finalization (after 4). +6. **Phase 6** — music spec/catalog (after 2 and 4). +7. **Phase 7** — async client rehydration (after 5 and 6). +8. **Phase 8** — Wizard workflow concurrency (after 4). +9. **Phase 9** — Story Music router extract (after 5). +10. **Phase 10** — Story session controller (after 7). +11. **Phase 11** — Studio music `useStore` slice (after 6 and 7). +12. **Phase 12** — visible traceability (after 3 and 7). + +Graph (merge required on every arrow): `1 → {2,3}`; `3 → 4 → 5`; +`{2,4} → 6`; `{5,6} → 7`; `4 → 8`; `5 → 9`; `7 → 10`; `{6,7} → 11`; +`{3,7} → 12`. Details in `docs/development/EXECUTION_BASELINE.md`. + +## Residual risks to track separately + +- The real smoke produced valid H264/AAC media, but lyrical content can still + mix languages or stay generic. Treat that as a content-quality follow-up, + not as evidence that the identity/provenance chain failed. +- Closing the client during local music generation can leave a WAV without a + linked cue/candidate. Server-side finalization is still required. +- #137's prefix alias treats `English` as Spanish and `en español` as + English until #139 (or phase 2) lands. +- Generation-record v1 is a projection, not a second store, and is not + yet wired into launch writers. +- Two local stashes remain unaudited as product work: `stash@{0}` is a CI + workflow addition on `test/create_e2e_test`; `stash@{1}` is Hunyuan3D/ + model3d worker work. Do not apply or delete them without a human. + +## Standing rules + +- Boy scout: migrate visible copy of the touched UI zone, EN+ES in the same + commit, glossary first. Do not mass-translate the app. +- Workspace stays the product name; physical directories stay **Output folder**. +- No WanGP / models / launchers. No `agentActions.ts` unless the assigned + slice already owns it. +- `#48` stays draft unless a human asks to revive it. +- Video Editor drafts stay out of the global project registry until they have + durable server storage. +- Only one pending PR may touch `_launch_runtime.py`. Only one pending PR may + touch `useStore.ts`. Independent PRs may proceed in parallel when files do + not overlap. + +## Low-cost delegation protocol + +When work is orchestrated from Codex/ChatGPT, the lead agent delegates each +bounded implementation packet to `luna_worker` (configured by +`luna-worker.toml`). This is an engineering workflow convention, not a +product dependency. A packet must name the branch base, owned and forbidden +files, contracts/invariants, tests/commands, expected PR and stop conditions. +Luna makes one bounded PR and never merges it; the lead reviews the diff, +quality score and CI before asking a human to merge. Keep at most one open PR +per hot file (`_launch_runtime.py`, `useStore`, `agentActions`). If Luna is +unavailable, the lead executes the packet or asks for direction; it must not +silently substitute a broad uncontrolled agent. + +Reusable packet header: + +> **Execution context: Codex/ChatGPT — delegate the bounded implementation to +> `luna_worker`; lead coordinates and reviews.** diff --git a/fase1.md b/docs/archive/2026-09-06/architecture-wave/fase1.md similarity index 100% rename from fase1.md rename to docs/archive/2026-09-06/architecture-wave/fase1.md diff --git a/fase10.md b/docs/archive/2026-09-06/architecture-wave/fase10.md similarity index 100% rename from fase10.md rename to docs/archive/2026-09-06/architecture-wave/fase10.md diff --git a/fase11.md b/docs/archive/2026-09-06/architecture-wave/fase11.md similarity index 100% rename from fase11.md rename to docs/archive/2026-09-06/architecture-wave/fase11.md diff --git a/fase12.md b/docs/archive/2026-09-06/architecture-wave/fase12.md similarity index 100% rename from fase12.md rename to docs/archive/2026-09-06/architecture-wave/fase12.md diff --git a/fase2.md b/docs/archive/2026-09-06/architecture-wave/fase2.md similarity index 100% rename from fase2.md rename to docs/archive/2026-09-06/architecture-wave/fase2.md diff --git a/fase3.md b/docs/archive/2026-09-06/architecture-wave/fase3.md similarity index 100% rename from fase3.md rename to docs/archive/2026-09-06/architecture-wave/fase3.md diff --git a/fase4.md b/docs/archive/2026-09-06/architecture-wave/fase4.md similarity index 100% rename from fase4.md rename to docs/archive/2026-09-06/architecture-wave/fase4.md diff --git a/fase5.md b/docs/archive/2026-09-06/architecture-wave/fase5.md similarity index 100% rename from fase5.md rename to docs/archive/2026-09-06/architecture-wave/fase5.md diff --git a/fase6.md b/docs/archive/2026-09-06/architecture-wave/fase6.md similarity index 100% rename from fase6.md rename to docs/archive/2026-09-06/architecture-wave/fase6.md diff --git a/fase7.md b/docs/archive/2026-09-06/architecture-wave/fase7.md similarity index 100% rename from fase7.md rename to docs/archive/2026-09-06/architecture-wave/fase7.md diff --git a/fase8.md b/docs/archive/2026-09-06/architecture-wave/fase8.md similarity index 100% rename from fase8.md rename to docs/archive/2026-09-06/architecture-wave/fase8.md diff --git a/fase9.md b/docs/archive/2026-09-06/architecture-wave/fase9.md similarity index 100% rename from fase9.md rename to docs/archive/2026-09-06/architecture-wave/fase9.md diff --git a/3D_VIDEO_LLM_HANDOFF.md b/docs/archive/2026-09-06/handoffs/3D_VIDEO_LLM_HANDOFF.md similarity index 100% rename from 3D_VIDEO_LLM_HANDOFF.md rename to docs/archive/2026-09-06/handoffs/3D_VIDEO_LLM_HANDOFF.md diff --git a/RHYTHM_AGENT_HANDOFF.md b/docs/archive/2026-09-06/handoffs/RHYTHM_AGENT_HANDOFF.md similarity index 100% rename from RHYTHM_AGENT_HANDOFF.md rename to docs/archive/2026-09-06/handoffs/RHYTHM_AGENT_HANDOFF.md diff --git a/grokrespuesta.md b/docs/archive/2026-09-06/handoffs/grokrespuesta.md similarity index 100% rename from grokrespuesta.md rename to docs/archive/2026-09-06/handoffs/grokrespuesta.md diff --git a/informe.md b/docs/archive/2026-09-06/handoffs/informe.md similarity index 100% rename from informe.md rename to docs/archive/2026-09-06/handoffs/informe.md diff --git a/planmejora.md b/docs/archive/2026-09-06/handoffs/planmejora.md similarity index 100% rename from planmejora.md rename to docs/archive/2026-09-06/handoffs/planmejora.md diff --git a/scheduler.md b/docs/archive/2026-09-06/handoffs/scheduler.md similarity index 100% rename from scheduler.md rename to docs/archive/2026-09-06/handoffs/scheduler.md diff --git a/docs/archive/README.md b/docs/archive/README.md new file mode 100644 index 00000000..49f925bc --- /dev/null +++ b/docs/archive/README.md @@ -0,0 +1,22 @@ +# Archivo de desarrollo — lectura bajo demanda + +Estos documentos conservan decisiones, requisitos y evidencia de sesiones previas. +**No son instrucciones vigentes ni una lista de tareas pendientes.** Empieza por +[CURRENT_WORK](../development/CURRENT_WORK.md). No leas este árbol rutinariamente. +Archivar no significa que todas las propuestas estén implementadas o canceladas. + +- [Ola F1–F12 de arquitectura](2026-09-06/architecture-wave/EXECUTION_BASELINE.md): + baseline, cola original y paquetes `fase1.md`–`fase12.md`. Sus estados y base main + caducaron; el resumen vigente conserva los pendientes verificables. +- [Handoff 3D de agosto](2026-09-06/handoffs/3D_VIDEO_LLM_HANDOFF.md) y + [ritmo/Wizard](2026-09-06/handoffs/RHYTHM_AGENT_HANDOFF.md): snapshots de otras ramas. +- Análisis históricos, no roadmap aprobado completo: + [grokrespuesta](2026-09-06/handoffs/grokrespuesta.md), + [informe](2026-09-06/handoffs/informe.md), + [planmejora](2026-09-06/handoffs/planmejora.md), + [scheduler](2026-09-06/handoffs/scheduler.md). + +Las rutas en bloques de código/prosa históricos describen su checkout original; +no prometen existir en este archivo. Para recuperar contexto adicional usa Git por +SHA. Las guías de usuario, contratos activos, prompts consumidos por la aplicación +y planes en curso permanecen en sus ubicaciones funcionales. diff --git a/docs/development/BRANCHING.md b/docs/development/BRANCHING.md index 33f23909..7f9f39fd 100644 --- a/docs/development/BRANCHING.md +++ b/docs/development/BRANCHING.md @@ -7,7 +7,7 @@ during transition, but new work must not use that ambiguous legacy name. ## Ordinary agent work -1. Read local AGENTS instructions when present, CONTRIBUTING, SLICE_QUEUE and the +1. Read local AGENTS instructions when present, CURRENT_WORK, SLICE_QUEUE and the assigned acceptance criteria. Inspect branches, PRs and ownership before editing. 2. Fetch origin and create an isolated feature/fix worktree from origin/development. Never switch the branch in another agent's shared checkout or carry untracked @@ -75,7 +75,7 @@ committed checklist. Mutable transition evidence belongs in the PR/handoff. ```text HocusPocus now integrates ordinary work in development; main is the published line. -Fetch origin, read CONTRIBUTING.md, docs/development/BRANCHING.md and SLICE_QUEUE.md, +Fetch origin, read docs/development/CURRENT_WORK.md, docs/development/BRANCHING.md and SLICE_QUEUE.md, plus any local AGENTS.md instructions. Create feature/fix work in isolated worktrees from origin/development; open PRs with --base development. Use the actual PR base for ratchet (explicit BASE_REF or BASE_SHA while wrappers are transitioning). diff --git a/docs/development/CHARACTER_SPEECH_WORKSHOP.md b/docs/development/CHARACTER_SPEECH_WORKSHOP.md index e26ce78d..35cb92a8 100644 --- a/docs/development/CHARACTER_SPEECH_WORKSHOP.md +++ b/docs/development/CHARACTER_SPEECH_WORKSHOP.md @@ -1,6 +1,6 @@ # Taller de habla 2D — preparación manual primero -Base: development `ebed43fd`, 2026-09-06. Complementa +Base: development `a0bf91c6` (#200 mezclado), 2026-09-07. Complementa [el plan raster](CHARACTER_SPEECH_RASTER_PLAN.md), no declara R2–R4 terminados. ## Alcance de este PR @@ -30,10 +30,11 @@ Base: development `ebed43fd`, 2026-09-06. Complementa Su hallazgo sobre recuperación de borradores se corrige antes de publicar. - [x] Validación local final del parche de recuperación, incluida navegación real con API simulada y desmontaje comprobado antes de recuperar el borrador. -- [ ] PR a development; comprobar su estado remoto, no inferirlo de esta lista. -- [ ] CI verde sobre HEAD exacto y revisión remota completada o dispensada. -- [ ] Merge normal a development (no publicar main). -- [ ] Prueba artística de un personaje hablando (pendiente, fuera de este PR). +- [x] PR [#200](https://github.com/IAnMove/hocuspocus/pull/200) a development; + HEAD `7fa0c6b5`; merge `a0bf91c6`. Comprobado en remoto, no inferido de esta lista. +- [x] CI required verde sobre ese HEAD. Independent QA/Bugbot neutrales no son + aprobación. Sin publicar main ni reiniciar apps compartidas. +- [ ] Prueba artística de un personaje hablando (pendiente, fuera de #200). ## Alternativas y decisión diff --git a/docs/development/CURRENT_WORK.md b/docs/development/CURRENT_WORK.md new file mode 100644 index 00000000..8ff9d41e --- /dev/null +++ b/docs/development/CURRENT_WORK.md @@ -0,0 +1,103 @@ +# Estado de desarrollo y punto de entrada + +Verificado el 7 de septiembre de 2026 contra `origin/development` **`a0bf91c6`**. +Es una fotografía con evidencia, no un sustituto de Git. Antes de reservar trabajo: +`git fetch origin development`, consultar PR abiertos y comprobar sus archivos. + +## Lectura mínima + +Lee este documento y el contrato del dominio que vas a modificar. Para contribuir, +consulta [BRANCHING](BRANCHING.md) y [AGENT_QA_POLICY](AGENT_QA_POLICY.md). +La [cola](SLICE_QUEUE.md) contiene solo pendientes. No leas todo `docs/` ni el +[archivo histórico](../archive/README.md) al iniciar una sesión. Los planes antiguos +no autorizan acciones ni representan el estado actual. + +## Integrado: no volver a implementar + +| Trabajo | Evidencia de integración | Límite de la afirmación | +|---|---|---| +| Contrato de idioma de letras | #139, #141 | No garantiza fidelidad de toda canción generada | +| GenerationRecord con CAS y autoridad de proyección | #138, #142 | No es un segundo scheduler ni prueba cobertura de todos los productores | +| Reserva musical idempotente | #143 | Distinguir reserva, ejecución y publicación | +| Finalización musical en servidor | #158 | Revisar su contrato antes de proponer otra implementación | +| Catálogo/spec musical y rehidratación | #159, #160, #162; fake worker #163 | Fake worker no acredita calidad de audio real | +| Extracción I/O de estado Director | #167 | Locks, reconciliación, borrado y ejecución siguen en el pipeline | +| Adopción H3, guías y finalización de prompts | #170, #172, #174, #178, #179 | Mantener diálogos literales y fixtures; no rehacer refactor | +| Policy/idioma/Creative H3 | #185 | Pruebas de contrato no demuestran éxito audiovisual universal | +| Labs/Wizard L0–L12 | #182, #183, #186–#189, #192, #194, #196, #197 | Entregas integradas; #197 congela L1–L4 y L9 como resueltos. Quedan límites de validación indicados abajo | +| Vídeo procedural y galería/plantillas | #168, #169, #173, #175, #177, #180, #181, #184 | No equivale a completar toda la hoja de ruta procedural | +| Inspección GLB y parches faciales | #190, #193, #195 | Router de inspección de #195 todavía sin montar; parches tienen límites de piloto | +| Taller de habla 2D (preparación manual) | #200 | Panel, borrador, recarga y e2e simulado. El test del panel evita aserciones HTMLElement-vs-null (~260 MiB RSS). No es validación artística de un personaje hablando ni cierra R2–R4 | + +La integración es en **development**. No implica que el servidor local esté usando +esa revisión ni que exista una publicación de aplicación en main. + +## En curso al comprobarlo + +Al cerrar esta revisión el taller de habla ya está integrado (#200, merge +`a0bf91c6`). Escenas 3D sigue en un PR abierto, no integrado. Estado por dominio: + +- **Escenas 3D reales**: PR [#198](https://github.com/IAnMove/hocuspocus/pull/198), + rama `feat/video3d-real-scene-mode`, cambios en + `PROCEDURAL_3D_SCENE_SPEC.md`, SceneAnimator, `features/scene3d`, dependencias e i18n. +- **Vídeo procedural**: conservar el checkpoint `work/procedural-video-pilot-checkpoint`; + consultar [PROCEDURAL_VIDEO_ROADMAP](PROCEDURAL_VIDEO_ROADMAP.md) y el documento del + subdominio asignado. No mezclar el checkpoint en bloque ni asumir que todo su + historial está pendiente. + +«En curso» se basa en rama y diff, no en inferir que un agente siga conectado. +No limpiar estos worktrees, stashes, archivos sin seguimiento ni outputs. El estado +local y sus rutas de máquina se mantienen fuera de Git en `ESTADO_LOCAL.md`. + +## Pendiente: refactor y validación + +1. **Director**: delimitar locks/reconcile/delete/observer y sus contratos antes de + extraer; después cómic, H3, reparación/rerun y ciclo de vida. No existe todavía + un `PipelineRuntime` tipado completo. No mover helpers enteros por nombre si + mezclan I/O con generación o scheduler. +2. **Runtime HTTP**: las cuatro rutas Story Music siguen en `_launch_runtime.py`. + Extraer un router de dominio con cableado mínimo y un único propietario del archivo. +3. **Estado UI**: falta la extracción cohesiva de sesión Story (carga, borradores, + guardado/rehidratación) y continuar el slice musical de `useStore`. +4. **Wizard concurrente**: ya hay CAS de colección y recuperación 409; verificar + exclusión de efectos/pasos entre dos clientes y compatibilidad de checkpoints. + No volver a proponer CAS desde cero. La antigua F8 no está certificada completa. +5. **Trazabilidad**: comprobar cobertura real de productores→GenerationRecord→UI; + conservar una proyección y la autoridad de TaskRegistry/asset-manifest. La + antigua F12 no debe confundirse con Labs L12. +6. **H3 desde Studio**: comprobar propagación de policy desde cada petición UI; + el contrato API acepta la policy, pero la inspección del store dejó caminos + pendientes de comprobación. No inferir envío por existir el campo en el schema. +7. **Labs, cierre de validación**: seleccionar un `attemptId` concreto (la prueba + L12 titulada «take 2» usa `shot_numbers: [2]` y `selected_latest`); comprobar + navegación móvil real; prueba audiovisual acotada y equivalencia UI/Wizard. + #196 no repitió GPU. Sus checks verdes no cubren esas ausencias. +8. **Producto separado del refactor**: fidelidad de letras/idioma y evaluación real + de Creative/audio H3. Sin repetir matrices masivas ni inventar resultados. +9. **Entrega**: reconsultar estado de protecciones y preparar una release a main + solo dentro de su autorización. Esta limpieza documental no publica ni cambia + reglas de GitHub. + +Orden recomendado: terminar los cambios locales ya empezados, cerrar lagunas de +validación y abordar un único contrato de refactor por PR. Detalle de ownership y +priorización en [SLICE_QUEUE](SLICE_QUEUE.md). + +## Contratos: consultar por tarea + +| Tarea | Referencia | +|---|---| +| Capas y dependencias | [ARCHITECTURE_FOUNDATION](ARCHITECTURE_FOUNDATION.md), [ARCHITECTURE_MAP](ARCHITECTURE_MAP.md) | +| Identidad y procedencia | [DOMAIN_MODEL_AND_ASSET_PROVENANCE](DOMAIN_MODEL_AND_ASSET_PROVENANCE.md), [GENERATION_RECORD](GENERATION_RECORD.md) | +| Música | [MUSIC_SUBMISSION](MUSIC_SUBMISSION.md), [MUSIC_FINALIZATION](MUSIC_FINALIZATION.md), [MUSIC_MODEL_CONTRACT](MUSIC_MODEL_CONTRACT.md) | +| Wizard | [WIZARD_ACTION_RUNNER](WIZARD_ACTION_RUNNER.md), [WIZARD_WORKFLOW_RUNTIME](WIZARD_WORKFLOW_RUNTIME.md) | +| Labs | [LABS_WIZARD_ACTION_MATRIX](LABS_WIZARD_ACTION_MATRIX.md): referencia detallada/fixture, no checklist de inicio | +| Calidad y textos | [CODE_HEALTH](CODE_HEALTH.md), [INTERNATIONALIZATION](INTERNATIONALIZATION.md), [LOCAL_VALIDATION](LOCAL_VALIDATION.md) | + +## Cómo mantener este estado sin volver a crear una biblia + +Al integrar un contrato, mueve su pendiente a «Integrado» con PR y límite de +validación. Retira la entrada temporal de «En curso». Si la tabla crece demasiado, +resume por dominio y deja el historial de commits en Git; no pegues conversaciones. +Los handoffs caducan al integrarse o ser sustituidos. Conserva decisiones y evidencia +en el archivo, pero no su autoridad operativa. Una fecha antigua por sí sola no +convierte un contrato técnico vigente en material descartable. diff --git a/docs/development/EXECUTION_BASELINE.md b/docs/development/EXECUTION_BASELINE.md index 2e29e982..339e550a 100644 --- a/docs/development/EXECUTION_BASELINE.md +++ b/docs/development/EXECUTION_BASELINE.md @@ -1,100 +1,18 @@ -# Architecture execution baseline +# Contratos de ejecución y baseline histórico -Status: living register for the 12-phase wave (`fase1.md`–`fase12.md`). -Verified against `origin/main` **`9ac4cacb`** (2026-09-05). +El registro del 5 de septiembre fue sustituido como cola por +[CURRENT_WORK](CURRENT_WORK.md) y [SLICE_QUEUE](SLICE_QUEUE.md). +El [original completo](../archive/2026-09-06/architecture-wave/EXECUTION_BASELINE.md) +se conserva para trazabilidad; no seguir sus órdenes de ramas ni sus estados de PR. -This document is the single queue for that wave. Working notes under -`comunicaciones/` are historical evidence only. +Autoridades que siguen vigentes: -## Authority by datum +- Tareas, eventos, espera/cancelación: TaskRegistry y cola durable. +- Story/cues/candidatos/producciones: biblioteca Story e IDs de dominio. +- Bytes y provenance publicados: asset-manifest junto al archivo. +- GenerationRecord: proyección durable con CAS; no otro scheduler o catálogo. +- `workspace_id` es colección opcional; `output_folder` es ubicación física. -| Datum | Authority | Not authority | -|---|---|---| -| Canonical tasks, job events, wait/cancel | `TaskRegistry` / `app/services/task_manager.py` and the durable generation queue | Generation-record JSON, Activity cards, chat prose | -| Story project, cue, song candidate, production | Story library (`.story-library-v1.json`) and Story domain IDs | Titles, `v1` labels, filenames, Wizard in-memory reports | -| Published bytes and provenance | Adjacent `.meta.json` asset-manifest v1 | Generation-record projection, gallery order | -| Generation attempt lifecycle | **Projection** over asset-manifest + provenance + job lifecycle (`generation-record v1`, #138) | A second scheduler, a second media store | - -`GenerationRecord` does not own GPU workers, file bytes or Story candidates. -Writers stay in the existing stores. Wiring into `_launch_runtime.py` is a -later sequential PR (phases 4–5). - -Workspace **collection** (`workspace_id`) is optional. `output_folder` is the -physical directory name. Do not invent a collection to satisfy a schema. - -## Phase graph - -Each arrow requires the **merge** of the source phase into `origin/main`, not -merely an open PR. - -```text -1 → {2, 3} -3 → 4 → 5 -{2, 4} → 6 -{5, 6} → 7 -4 → 8 -5 → 9 -7 → 10 -{6, 7} → 11 -{3, 7} → 12 -``` - -Hotspot rule: at most one open PR may edit `_launch_runtime.py`, `useStore.ts`, -`agentActions.ts`, `StoryLabPanel.tsx`, or Director/Wizard runtime. Branches -start from current `main`; they are not stacked. - -## Delivery matrix - -Columns are independent. Do not infer merge from CI, or CI from a previous -commit's Cursor review. - -| Entrega | Diseñado | Implementado | Commit | PR | CI del head | Cursor del head | Merge | Validación real | SHA | -|---|---|---|---|---|---|---|---|---|---| -| #135 MiniMax-Music3 | sí | sí | sí | #135 | verde al merge | 5 bugs corregidos en el head mezclado | **sí** `a899a8cc` | no (smoke local aparte) | head `93287183` | -| #138 generation-record v1 | sí | sí (proyección) | sí | #138 | verde al merge | 5 bugs corregidos (`b66ea0a9`) | **sí** `3f14b0e0` | no | head `b66ea0a9` | -| #137 lyrics guard | sí | sí (librería) | sí | #137 | verde al merge | alias `startswith` defectuoso quedó en main | **sí** `9ac4cacb` | no | head `8c696b26` | -| #136 docs cola | sí | sí | `b2bdad47` + este commit | #136 | verificar head nuevo | verificar head nuevo | no | N/A | ver PR | -| #139 lyrics alias tokens | sí (F2.3 parcial) | sí (prefijos) | `a6b7b0ff` | #139 | verde | Bugbot SUCCESS | no | no | `a6b7b0ff` | -| #140 Story song pending | sí (cliente) | sí (pending antes de generate) | `dc63eb5b` | #140 | verde en `dc63eb5b` | hallazgos de `5d513534` corregidos en `dc63eb5b`; Bugbot del head nuevo pendiente | no | no | `dc63eb5b` | - -Stashes (do not apply or delete): `stash@{0}` CI e2e on `test/create_e2e_test`; -`stash@{1}` Hunyuan3D/model3d on `feat/3d-compositor-recipe`. - -Cursor opened `origin/cursor/music-recovery-persistence-6c38` (`ae76c653`) -without a PR. #140 already contains the equivalent persist/reattach fix. -Do not land that branch unless a human compares it with `dc63eb5b`. - -## What #135/#137/#138/#139 still leave open - -Verified on `9ac4cacb` plus the open PR heads. Do not copy old Cursor -findings onto a SHA that already fixed them. - -| Source | Already in tree | Still missing | -|---|---|---| -| #135 | Local ACE-Step + MiniMax-Music3, download, 300s clamp, captions, generate without API key | Server-side song attach; lyrics guard not wired; generation-record not wired | -| #137 | Spanish contamination + bounded CJK/Arabic strip; `[Verse]` allowed | Prefix aliases on main (`English`→es, `en español`→en); empty vocal / unevaluable language / Estonian-as-Spanish; destructive repair-by-default; wiring to generate | -| #138 | Portable generation-record projection; cancel/retry/timing mapping | Empty-list patch semantics; write-point CAS; optional workspace collection; no producer wiring | -| #139 | Token aliases longer than 2 letters | Remaining F2 corpus (empty vocal, unsupported language ≠ ok, protected multiline exact, no destructive default) | -| #140 | Pending `song-…` before generate; sidecar recovery; refuse pending staging | Server finalization without browser (phase 5); launch still blocking POST | - -## Next slices (this wave) - -Mapped onto `fase1.md`–`fase12.md`. Do not open a slice whose arrow is not -merged. - -1. **Phase 1 (this PR)** — this baseline. -2. **Phase 2** — continue #139 after phase 1 merges: unevaluable languages, - exact protected spans, no destructive default. -3. **Phase 3** — generation-record authority after phase 1 merges. -4. **Phase 4** — idempotent music submit (minimal `_launch_runtime.py`). -5. **Phase 5** — server-side music finalization (launch sequential after 4). -6. **Phase 6** — music spec/catalog after 2 and 4 merge. -7. **Phase 7** — async client rehydration after 5 and 6. -8. **Phase 8** — Wizard workflow concurrency after 4. -9. **Phase 9** — Story Music router extract after 5. -10. **Phase 10** — Story session controller after 7. -11. **Phase 11** — Studio music `useStore` slice after 6 and 7. -12. **Phase 12** — visible traceability after 3 and 7. - -Real media smoke remains `bash scripts/run_real_media_smoke.sh` with explicit -confirmation. It is never GitHub Actions. +Contratos detallados: [GENERATION_RECORD](GENERATION_RECORD.md) y +[DOMAIN_MODEL_AND_ASSET_PROVENANCE](DOMAIN_MODEL_AND_ASSET_PROVENANCE.md). +Las antiguas F1–F12 están archivadas; su numeración no es Labs L0–L12. diff --git a/docs/development/LABS_WIZARD_ACTION_MATRIX.md b/docs/development/LABS_WIZARD_ACTION_MATRIX.md index 4b380c1f..a8e10e1b 100644 --- a/docs/development/LABS_WIZARD_ACTION_MATRIX.md +++ b/docs/development/LABS_WIZARD_ACTION_MATRIX.md @@ -1,6 +1,9 @@ # Labs ↔ Wizard action matrix (L0) -Status: freeze of current contracts. This document does not implement the later phases. +Status: detailed L0 fixture/reference with L5–L12 updates; not the startup checklist. +For current delivery state and remaining QA, read [CURRENT_WORK](CURRENT_WORK.md). +The machine fixture preserves historical classifications: a frozen defect ID is +not proof that its defect is still present after the linked fixes. ## Base @@ -20,14 +23,14 @@ Status: freeze of current contracts. This document does not implement the later - `actor=user` stays on UI handlers; `actor=wizard` stays on the runner. Both must share the domain operation listed here. - Classifications: `operativa`, `condicional`, `solo_navegacion`, `solo_informacion`, `no_expuesta`, `sin_implementar`. -## Known gaps frozen for later phases +## Historical gap IDs and implementation follow-up | Id | Phase | Summary | |---|---|---| -| `fused_dropped_by_model_for_manifest` | L1 | Addressed: fused IDs stay fused; references use minimax_h3_ref2va_fused_turbo; frames use minimax_h3_fused_turbo. | -| `partial_global_profile_guard` | L2 | Addressed: seriesProviderMatchesGlobal includes writingBaseUrl, flowShift, audioShift and modelProfile. | -| `approve_all_replaces_chosen_takes` | L3 | Addressed: pending takes / all_latest keep valid finals; replace_latest and explicit selected_latest remain replace paths. | -| `script_shots_dialogue_desync` | L4 | Addressed: script edits annotate stale shots; render refuses them; sync is an explicit operation. | +| `fused_dropped_by_model_for_manifest` | L1 | Addressed in #183/#197: fused IDs stay fused; references use minimax_h3_ref2va_fused_turbo; frames use minimax_h3_fused_turbo. Real GPU verification was not repeated by L12. | +| `partial_global_profile_guard` | L2 | Addressed in #183/#197: seriesProviderMatchesGlobal includes writingBaseUrl, flowShift, audioShift and modelProfile. Frozen episode snapshots stay. | +| `approve_all_replaces_chosen_takes` | L3 | Addressed in #183/#197: pending takes / all_latest keep valid finals; replace_latest and explicit selected_latest remain replace paths. L12 does not prove selection of a specific attemptId. | +| `script_shots_dialogue_desync` | L4 | Addressed in #183/#197: script edits annotate stale shots; render refuses them; sync is explicit. Full UI-to-real-render validation is separate. | | `blocked_always_empty` | L5 | Addressed: availability is derived as executable / needs_data / blocked / requires_navigation. | | `stage_series_comic_unregistered` | L6 | Addressed: stageSeriesComic is exposed as `stage_series_comic` on the existing Series comic handoff. | | `wizard_auto_approves_canon` | L7 | Addressed: episode creation may approve only a brand-new canon base from the same request, never pending canon on an existing series. | @@ -1295,7 +1298,7 @@ Executable coverage lives in `ui/tests/labsWizardL12.test.mjs`, plus the L7–L1 | «He descubierto ChatGPT» | `syncShotsFromScript` keeps the literal and marks the speaking shot stale. | | Generate pending shots in quick mode | Wizard parses `render_series_shots` `missing`. Fused 4-step payload is covered by `tests/test_series_render.py`. This PR did **not** run a GPU generation. | | Choose latest pending takes | `bulkApproveSelections({ replaceFinals: false })` keeps existing finals. | -| Use take 2 for this shot | `review_series_attempts` `selected_latest` with `shot_numbers: [2]`. | +| Use take 2 for this shot | Partial coverage only: this selects the latest attempt of shot 2, not a specific take 2. Add explicit attemptId coverage. | | Make a comic of this episode | `stage_series_comic` remains the existing operation. | | Assemble without enough takes | `missingAssemblyShotOrders` lists missing shot numbers; assemble throws `Faltan`. | | Workspace change in flight | Covered by `ui/tests/storyAsyncOwnership.test.mjs`. | @@ -1303,4 +1306,4 @@ Executable coverage lives in `ui/tests/labsWizardL12.test.mjs`, plus the L7–L1 | Reload with live generation | `reusableInFlightSongCandidate` reuses the pending job candidate. | | Invalid provider action/fields | Unknown types and invalid `render_mode` parse to no actions. | -Remaining documented gaps, not claimed tested by this suite: `fused_dropped_by_model_for_manifest`, `approve_all_replaces_chosen_takes` (UI “use pending takes” now keeps finals; `all_latest` vs `replace_latest` still exist), `script_shots_dialogue_desync`. No real audiovisual generation was repeated here. +Historical gap IDs above have fixes in #183; they are not all open defects. Remaining validation: a specific attemptId, real mobile browser navigation and bounded audiovisual/UI-to-Wizard checks. No real audiovisual generation was repeated here. diff --git a/docs/development/SLICE_QUEUE.md b/docs/development/SLICE_QUEUE.md index 32d52405..30f3ae65 100644 --- a/docs/development/SLICE_QUEUE.md +++ b/docs/development/SLICE_QUEUE.md @@ -1,297 +1,50 @@ -# Slice queue - -## Current integration base - -New ordinary work branches from `origin/development` and targets `development`. -`main` is reserved for the published Pinokio version. Follow -[BRANCHING.md](BRANCHING.md) for releases, hotfixes and transition of existing PRs. -Historical main/merge records below retain their original meaning; do not rewrite -accepted history or infer that a PR is merged from its existence. - -Humans own merges as an operational act; that click is not a technical code -review. Agents own technical review and QA. See -`docs/development/AGENT_QA_POLICY.md`. Agents do not merge until checks are -green, and never open a second PR on the same hotspot. - -PRs should be **medium and cohesive** (about 300–1,000 net lines) with one -verifiable contract. Do not open a PR per property, action or tiny component. - -Canonical sources in git: - -- Domain identities: `docs/development/DOMAIN_MODEL_AND_ASSET_PROVENANCE.md` -- i18n boy scout: `docs/development/INTERNATIONALIZATION.md` -- Architecture contracts: `docs/development/ARCHITECTURE_FOUNDATION.md` -- Independent review/QA: `docs/development/AGENT_QA_POLICY.md` and - `docs/development/QA_ACCEPTANCE.md` -- Execution baseline and 12-phase wave: `docs/development/EXECUTION_BASELINE.md` - and `fase1.md`–`fase12.md` (repo root). Working notes under `comunicaciones/` - are session handoff only. - -Working notes under `comunicaciones/` are session handoff only. They are -gitignored and are not canonical. - -## Landed on main (as of #137) - -`main` points at merge #137 (`9ac4cacb`, 2026-09-05). That commit sits on -#138 (`3f14b0e0`) and #135 (`a899a8cc`). The queue below records what is -present in that tree; the numbered history is kept so earlier slice -decisions are not rewritten. MiniMax-Music3, generation-record v1 and the -lyrics-language library are landed. `_launch_runtime.py`, `useStore.ts` and -`agentActions.ts` are free for **one** sequential PR: durable Story song -identity. - -Asset-manifest v1 writers: Studio generate (simulated, WGP, H3, SFX), Tools -upscale/revoice, Recast/Repaint/Outpaint, MiniMax image, Series assembly, 3D, -Rig, Director H3 join, Director timing attach, alternative songs, scene -recording, Video Editor screenshot/export, comic animatic. - -Sidecar failure: Hunyuan3D and Rig keep the GLB when provenance write fails. - -Domain provenance: `workspace_id` is the collection; `output_folder` is the -physical directory. `GenerationProvenance` / `CommandContext` distinguish -initiator (`origin.actor` / `tool` / `capability`) from provider/model. -Inspector timing reads `queue_ms` / `inference_ms` / `total_ms`. - -Studio+Wizard provenance landed (#95): generation task IDs are assigned before -publish so Wizard→Studio→asset can share one durable identity. - -`useStore` slices (facade kept): theme, settings (includes model-visibility -focus), developerMode, sidebar, retake dialog, Director, gallery/workspace -(#101), and LLM (#107). Slices bind through `bindSlice` without `as never`. -`developerModeSlice` no longer writes `mediaFilter`; the facade still leaves -`auditdev` when developer mode turns off. Gallery/workspace and LLM extraction -are landed; the remaining generation orchestration stays behind the public -facade and must be extracted in cohesive slices. - -Story Lab UI extracts: - -- #88 shared `ReferenceGallery`, `LocationEditor`, `CharacterEditor`, - `BeatEditor`, `storyLabVisuals` / `StoryLabVisualsProvider`; World, - Characters, Relationships and Structure tabs. -- #91 Music, Trailer, Productions and Compact workspace, with `storyLab` EN+ES. -- #97 split those extracted tabs into smaller panels and added the code-health - PR table (`scripts/code_health.py --check --markdown`). -- #98 Overview + generation-agent panel, EN+ES. -- #100 Assets tab extracted with EN/ES. Assets is no longer remaining in - `StoryLabPanel`. -- #103 added `StoryAssemblyTab`, `StoryLabLibraryChrome` and the shared - `storyLabTabs` registry. Assembly and the library header/tab/project-type/ - preparation chrome are no longer pending extractions. - -Visible i18n is catalog-backed in the migrated chrome, with matching EN+ES -keys: foundation, Extra info inspector/dialog, Assets, Story Lab, Series Lab, -Director, Video Editor, workspaces, and the remaining Studio/creative UI -surfaces (#103, #105, #109). #108 also separates UI locale from conversation, -content, spoken and technical-prompt languages; UI locale must not select the -language of authored content or provider prompts. This remains incremental: -user-authored/generated text and untouched debt are not mass-translated. - -Recipe audio duration: generated audio is sized for its consumers (#93). -#21 was the earlier draft of that fix and is closed as superseded. - -Character Kits / Face Rig / cutout dialogue HOWUSEIT: #94 on `main`. #26 was -the older Cursor docs pass and is closed as superseded. - -`--markdown` without `--check` prints **Ratchet not evaluated.** (#99). CI -uses `--check --markdown`. - -### Cross-cutting work landed after #100 - -- **#104 — two-level UI architecture:** task navigation now exposes a - primary category and inner destination, with an explicit **Output folder** - control. The Wizard also has an embedded/sidebar presentation path. -- **#106 — LLM HTTP router:** LLM endpoints moved to `app/routers/llm.py`; - `_launch_runtime.py` keeps the mount and wiring contract. -- **#107 — LLM store slice:** the LLM drawer state and actions live in - `ui/src/stores/llmSlice.ts`; `useStore` remains the compatibility facade. -- **#110 — compositor boot intro:** the intro animation stays on the - compositor, reducing per-frame browser work. -- **#111 — H3 owner handoff:** legacy H3 GPU ownership is stabilized with - scheduler coverage. -- **#112 — Director temporary audio:** transient Director audio slices are - hidden from the user-facing output flow while their jobs run. -- **#113 — Director server audio adoption:** Story audio that the server - already owns is adopted by name with its Workspace/output-folder context; - the browser does not round-trip the bytes before Director analyzes it. -- **#114 — new Story song before videoclip:** a request for a new song creates - a fresh `music_video` Story, writes and generates its vocal cue, then carries - that cue into Director. The reconciler no longer falls back to an unrelated - selected project/song. The `music-video-new` acceptance scenario covers the - identity chain. -- **#115 — media card viewport sizing:** rendered output cards and their - virtualization share a viewport cap, including vertical-resize invalidation, - so cards stay usable inside the feed. - -## Integrated slices (#116–#120) - -All five PRs are merged into `main` and their required CI checks were green at -merge. The merge commits are recorded here so a handoff never confuses a -prepared branch or an in-progress check with an accepted change. - -- **#116 — documentation after #115:** merged as `215ad2a`; refreshed the - queue and Wizard roadmap for the post-#115 state. -- **#117 — Studio configuration slice:** merged as `bfd4e9d`. The typed - `studioConfigurationSlice` owns Studio form/configuration state while - `startGeneration` and Tools execution stay in `useStore`; the public facade - and architecture coverage remain intact. The extraction reduces - `useStore.ts` from 10,239 to 9,741 lines. -- **#118 — Story Lab production controller:** merged as `e545836`. The - `storyProductionController.ts` owns Story Lab → Director production handoff - for film/trailer and music-video flows, including model/reference/audio - preparation. The extraction reduces `StoryLabPanel.tsx` from 4,688 to 4,395 - lines without touching `useStore.ts` or `_launch_runtime.py`. -- **#119 — exact Story song → music-video identity/provenance:** merged as - `4bc7376`, with simulated E2E and Cursor checks green. The opt-in real smoke - generated the requested song and an H264/AAC video of 19.75 seconds. The - harness's initial false negative came from selecting a lateral `Untitled - story` project; exact-title selection is now covered by the accepted flow. -- **#120 — code-quality trend score:** merged as `658a1c3`. The current - aggregate is **48.7/100**: complexity **52.1**, concentration **53.3**, - oversized-file health **28.5**, and modularity **62.2**; this is **+2.2** - against the historical committed baseline. It is a diagnostic trend signal, - not a CI blocker or quality certificate; the existing ratchet remains the - guardrail. CI publishes the score and comparison in PRs. - -## Queue history (original order, statuses updated) - -1. **Domain provenance contract** — landed (#86). -2. **Typed Zustand composition** — landed (#87). -3. **Story Lab simple tabs** — landed (#88). -4. **Story Lab Music + Productions** — landed (#91, split further in #97). -5. **Story Lab Overview** — landed (#98). -6. **Story Lab Assets tab** — landed (#100). -7. **Story Lab assembly + library chrome** — landed (#103), including - `StoryAssemblyTab` and `StoryLabLibraryChrome` with EN/ES. -8. **`useStore` slices** — gallery/workspace landed (#101), Director is - extracted, and the LLM slice landed (#107). Keep the public facade and - extend `architectureSlices.test.mjs`; do not move all of `startGeneration` - in one PR. At most one open PR may touch `useStore.ts`. -9. **Backend by domain** — LLM router landed (#106). Continue with one - complete router + services per PR (Assets, Music, Series, Comics, …), - preserving route-table ordinals. Do not split `_launch_runtime.py` by line - count. -10. **Provenance applied by flow** — Studio+Wizard landed (#95), Story song → - Director was hardened by #112–#114/#119, Series → Comics exact - provenance landed (#124), and generation-record v1 landed as a - portable projection (#138). Remaining identity work is Story music - versions and cue-by-id recovery after the client closes. 3D+Director - already has folder-vs-Workspace provenance (#89). - -## Integrated slices (#121–#134) - -These PRs are merged into `main`. Do not re-plan them. - -- **#121 — documentation after #120:** `0d5b077`. -- **#122 — Wizard conversation `409` recovery:** `98b824a`. Concurrent - conversation writes merge/retry instead of silently overwriting. -- **#123 — semantic song/lyrics language:** `c4e45d2`. Requested lyric - language and quoted spans are preserved; UI locale does not choose content. -- **#124 — Series → Comics exact provenance:** `ecad72d`. Cross-domain - handoff keeps project/production/run/task/output IDs. -- **#125 — remove background Tool:** `020f37e`. -- **#126 — task cost reports:** `08e1adc`. -- **#127 — rich PR template:** `78ed61e`. -- **#129 — Tools image/video upscale:** `df146f2`. -- **#130 — nightly ACE-Step smoke recipe:** `227d0e8`. Uses the local - ACE-Step route, not a MiniMax Music model ID. -- **#131/#132 — local validation vs real smoke:** `94921fb` / `31c0a42`. - `scripts/validate_local.sh` is provider-free; real media is - `scripts/run_real_media_smoke.sh` with explicit confirmation. -- **#133 — Tools upscale worker extract:** `08993d5`. -- **#134 — Wizard workflow persist pinned to source workspace:** `247554a2`. - -## Integrated slices (#135–#137) - -These PRs are merged into `main`. Do not re-plan them. - -- **#135 — local MiniMax-Music3:** `a899a8cc`. ACE-Step and MiniMax-Music3 - are selectable local backends. Wizard download, duration clamp (300s), - caption preservation and local generate-without-API-key landed with the - feature. This was the hotspot PR on `_launch_runtime.py` / `useStore.ts` / - `agentActions.ts`. -- **#138 — generation-record v1:** `3f14b0e0`. Portable projection over - asset-manifest, provenance and job lifecycle. New modules only; wiring - into launch/Activity/Library is still sequential. -- **#137 — lyrics language guard:** `9ac4cacb`. Provider-free Spanish - contamination checks and bounded foreign-script repair. Not yet wired - into write-song/generate. A follow-up must replace prefix aliases - (`English` starts with `es`; `en español` starts with `en`) with exact - aliases plus tokens longer than two letters. - -Open, not landed (verify CI/Cursor on the current head; do not infer merge): - -- **#136 — this PR.** Execution baseline, phase graph and phase files. -- **#139 — lyrics alias tokens** (`a6b7b0ff`). Covers F2.3 prefixes only. -- **#140 — Story pending candidate** (`dc63eb5b`). Client persist-before-generate. - Does not touch `_launch_runtime.py`. Server finalization is phase 5. - -## Next medium PRs after #137 - -Keep these as separate, reviewable slices. Each `faseN.md` is the packet. -Do not open a slice whose graph arrow is not **merged**. - -1. **Phase 1 (this PR)** — execution baseline. Unlock 2 and 3 after merge. -2. **Phase 2** — continue #139: unevaluable languages, exact protected spans, - no destructive default. Library only. -3. **Phase 3** — generation-record authority (projection, CAS, no producers). -4. **Phase 4** — idempotent music submit; sole sequential `_launch_runtime.py` - owner until it merges. -5. **Phase 5** — server-side music finalization (after 4). -6. **Phase 6** — music spec/catalog (after 2 and 4). -7. **Phase 7** — async client rehydration (after 5 and 6). -8. **Phase 8** — Wizard workflow concurrency (after 4). -9. **Phase 9** — Story Music router extract (after 5). -10. **Phase 10** — Story session controller (after 7). -11. **Phase 11** — Studio music `useStore` slice (after 6 and 7). -12. **Phase 12** — visible traceability (after 3 and 7). - -Graph (merge required on every arrow): `1 → {2,3}`; `3 → 4 → 5`; -`{2,4} → 6`; `{5,6} → 7`; `4 → 8`; `5 → 9`; `7 → 10`; `{6,7} → 11`; -`{3,7} → 12`. Details in `docs/development/EXECUTION_BASELINE.md`. - -## Residual risks to track separately - -- The real smoke produced valid H264/AAC media, but lyrical content can still - mix languages or stay generic. Treat that as a content-quality follow-up, - not as evidence that the identity/provenance chain failed. -- Closing the client during local music generation can leave a WAV without a - linked cue/candidate. Server-side finalization is still required. -- #137's prefix alias treats `English` as Spanish and `en español` as - English until #139 (or phase 2) lands. -- Generation-record v1 is a projection, not a second store, and is not - yet wired into launch writers. -- Two local stashes remain unaudited as product work: `stash@{0}` is a CI - workflow addition on `test/create_e2e_test`; `stash@{1}` is Hunyuan3D/ - model3d worker work. Do not apply or delete them without a human. - -## Standing rules - -- Boy scout: migrate visible copy of the touched UI zone, EN+ES in the same - commit, glossary first. Do not mass-translate the app. -- Workspace stays the product name; physical directories stay **Output folder**. -- No WanGP / models / launchers. No `agentActions.ts` unless the assigned - slice already owns it. -- `#48` stays draft unless a human asks to revive it. -- Video Editor drafts stay out of the global project registry until they have - durable server storage. -- Only one pending PR may touch `_launch_runtime.py`. Only one pending PR may - touch `useStore.ts`. Independent PRs may proceed in parallel when files do - not overlap. - -## Low-cost delegation protocol - -When work is orchestrated from Codex/ChatGPT, the lead agent delegates each -bounded implementation packet to `luna_worker` (configured by -`luna-worker.toml`). This is an engineering workflow convention, not a -product dependency. A packet must name the branch base, owned and forbidden -files, contracts/invariants, tests/commands, expected PR and stop conditions. -Luna makes one bounded PR and never merges it; the lead reviews the diff, -quality score and CI before asking a human to merge. Keep at most one open PR -per hot file (`_launch_runtime.py`, `useStore`, `agentActions`). If Luna is -unavailable, the lead executes the packet or asks for direction; it must not -silently substitute a broad uncontrolled agent. - -Reusable packet header: - -> **Execution context: Codex/ChatGPT — delegate the bounded implementation to -> `luna_worker`; lead coordinates and reviews.** +# Cola vigente de refactor + +Base verificada: `origin/development` `a0bf91c6`, 2026-09-07. +Lee primero [CURRENT_WORK](CURRENT_WORK.md): integrado, en curso y límites de QA. +No uses la ola F1–F12 como cola actual; es distinta de Labs L0–L12. + +## Reservas y base + +- Trabajo ordinario desde `origin/development`, PR hacia `development`. + `main` es publicación: [BRANCHING](BRANCHING.md). +- Reconsultar PR y diff local antes de reservar. Máximo un PR pendiente por + `_launch_runtime.py`, `useStore.ts`, `agentActions.ts`, StoryLabPanel o runtime + Director/Wizard. No superponer cambios de otros agentes. +- Conservar prompts, IDs, provenance y fachadas. No mover código solo por reducir + líneas. PR cohesivos con contratos y pruebas; no uno por propiedad. +- Revisión/merge según [AGENT_QA_POLICY](AGENT_QA_POLICY.md) y autorización vigente + del usuario. Esta cola no concede permisos nuevos ni restablece excepciones de + handoffs antiguos. No activar auto-merge ni protecciones por limpiar documentos. + +## Pendientes elegibles: comprobar antes de reservar + +| Paquete | Propiedad prevista | Dependencia / alcance | +|---|---|---| +| Cierre de QA Labs | Tests UI/Wizard, browser y pruebas reales acotadas | #182–#196 integrados; no rehacer sus funciones. Diferenciar plano y attemptId, móvil y GPU | +| Router Story Music | Nuevo router + cableado mínimo runtime | Finalización/spec/rehidratación ya integrados (#158–#163); reservar runtime en exclusiva | +| Sesión Story | Controller/hooks de carga, draft, guardado y recuperación | Las pestañas ya se reorganizaron; preservar workspace fuente y CAS | +| Slice musical Studio | `useStore` y slice musical | Reutilizar catálogo/spec existente; no extraer todo startGeneration | +| Director siguiente corte | Helpers de locks/reconcile/delete/observer y tests | I/O extraído en #167; caracterizar dependencias, elegir un solo contrato antes de mover | +| Concurrencia de ejecución Wizard | Runtime de workflow, autoridad backend y tests | CAS y 409 ya existen; verificar efectos/pasos concurrentes, no construir otra persistencia | +| Proyección visible de intentos | Producers/GenerationRecord/Activity según inventario | No segundo scheduler; elegir un flujo concreto y reservar sus hotspots | +| Policy H3 desde Studio | Adapter/request UI y tests de payload | No basta que el schema acepte policy; verificar envío y prompt efectivo | + +Después del próximo corte Director: cómic → H3 story-video → reparación/rerun → +validación/planificación → ciclo de vida con dependencias tipadas, ajustando orden +por acoplamiento real. Es orientación pendiente, no paquetes reservados ni una +orden de extraerlos todos sin revisión. + +## No volver a poner en cola + +Finalización musical del servidor, rehidratación, contrato de idioma/proyección, +I/O Director, refactor H3 y Labs L0–L12 ya tienen entregas integradas. Ver pruebas y +límites en [CURRENT_WORK](CURRENT_WORK.md); integrado no significa QA audiovisual +exhaustiva. Wizard 409 y Series→Comics provenance tampoco son tareas nuevas (#122, +#124). No restaurar el viejo backlog post-#120. + +## Documentación histórica + +[Archivo de la ola anterior](../archive/2026-09-06/architecture-wave/SLICE_QUEUE.md). +Consultar solo para recuperar una decisión o requisito concreto, nunca para elegir +base, permisos, PR pendientes o la próxima tarea.