# TrueTraceShorts V2 Operational Bridge (Sprint 1.5)

Use this reference when the user asks to connect the TrueTraceShorts V2 strategic spine to the existing AutoShortsBot pipeline without moving into mass production, rendering, posting, platform APIs, dashboards, or broad research automation.

## Purpose

Sprint 1 created a side-effect-free V2 strategy spine. Sprint 1.5 should make that spine operationally visible and testable while keeping the system a learning editorial/review system, not a blind content factory.

## Pre-flight / commit discipline

1. Check `git status --short` and current branch.
2. Run the full test suite before changing Sprint-1 work.
3. Review the key V2 files, especially:
   - `autoshorts/strategy/spine_v2.py`
   - `tests/test_strategy_spine_v2.py`
4. If clean, commit Sprint-1 work before Sprint-1.5 changes:
   - `git add autoshorts/strategy/spine_v2.py tests/test_strategy_spine_v2.py`
   - `git commit -m "Add strategy spine v2 quality gates and review package"`
5. If conflicts or unexpected changes exist, stop and report status rather than bundling unrelated work.

## Minimal bridge modules

Add only small, side-effect-free integration points:

- `autoshorts.content.to_candidate_v2`
  - Convert `ContentBriefV2 + ScriptInputV2`/script-like data into `VideoCandidateV2`.
  - No AI calls, no renderings, no network, no file writes.
  - Preserve explicit blanks/invalid fields so validation tests can catch them.

- `autoshorts.review.workflow_v2`
  - Classify candidates as `ready_for_review`, `blocked`, or `invalid`.
  - Use `validate_candidate_v2` and `StrategyScoreV2`.
  - Return structured reasons, not prose-only decisions.

- `autoshorts.cli.demo_review_batch_v2`
  - Generate at most 3 demo candidates.
  - Render ReviewPackageV2 to Telegram-safe text and optionally deterministic JSON.
  - No videos, no Telegram API, no platform API, no posting, no 30-day batch.

## ReviewPackageV2 serialization

Review packages should support deterministic serialization for future dashboard/audit work, but do not build the dashboard yet.

Recommended methods:

- `to_dict()`
- `to_json()`
- `from_dict()` when useful

Rules:

- Stable field order.
- No nondeterministic timestamps unless explicitly supplied.
- Include score breakdown, approval command, claim risk, AI disclosure, LinkedIn manual fields, platform fit, and hashes.

## Approval parser V2

Bind generated approval commands to a strict parser.

Required format:

```text
APPROVE <candidate_id> <version> <script_hash>
```

Validation:

- `candidate_id` must match exactly.
- `version` must match exactly.
- `script_hash` must match exactly.
- Missing parts block.
- Wrong hash blocks.
- Ambiguous text returns a clarification/blocked decision, never implicit approval.
- Media hash is optional until final video rendering exists.

## ScoreV2 calibration

Avoid scores that hand out 100/100 to merely good examples. The score must be useful for ranking.

Target distribution:

- Solid candidate: 75–85
- Very good candidate: 86–93
- Excellent candidate: 94–98
- 100: exceptional only

Tests should prove that:

- A solid candidate is not automatically 100.
- Weak human texture loses points.
- Generic hooks lose points.
- High saturation loses points.
- Weak first frame loses points.

ReviewPackageV2 should show both total score and score-breakdown rationales.

## Anti-example and human texture gates

Add concrete bad-example fields, not just abstract strategy labels:

- `anti_example` or `plausible_nonsense_example`
- `concrete_scene` for formats such as Attention Traps
- `human_texture_note`

Require anti-example for:

- AI Output Autopsy
- Workflow Teardown
- Digital Red Flags
- Decision Design

Attention Traps may use a concrete everyday scene instead. If `human_texture != NONE` but `human_texture_note` is empty, block the candidate.

## Minimal claim gate stub

Add only a manual validation foundation, not web scraping or auto research.

Module:

- `autoshorts.claims.fact_gate`

Minimal model:

- `Claim(text, claim_type, source, risk, note)`
- claim types: `opinion`, `experience`, `sourced_fact`, `risky_claim`
- risks: low/medium/high, or reuse the existing V2 claim-risk enum

Rules:

- Opinion needs no source.
- Experience needs `human_texture_note`.
- Sourced fact needs `source`.
- Risky claim needs `source`.
- High risk without source blocks.
- If factual claims exist, claim list must not be empty.

## Minimal AI-disclosure stub

Module:

- `autoshorts.compliance.ai_disclosure`

Model:

- `AIDisclosureReview`
  - youtube/tiktok/instagram/linkedin: yes/no/unclear
  - reason
  - synthetic media type: none, text-only assistance, abstract background, realistic person, realistic event, realistic voice, unclear

Rules:

- Any `unclear` blocks rendering.
- Realistic person/event/voice requires manual review.
- Text-only assistance or abstract background can be `no` when there is no realistic deception.
- No platform API here.

## LinkedIn manual platform only

Add `linkedin_manual` to platform fit/manual posting metadata only.

Include:

- LinkedIn title/hook variant.
- LinkedIn caption.
- B2B framing.
- Silent autoplay / readability note.
- Optional non-hype CTA.

Do not add LinkedIn OAuth, scheduling, publishing, or API integration in this sprint.

## Rendering backend note

If asked about Remotion during this phase, do not migrate. Add a note such as `docs/rendering_backend_options.md`:

- Current Python/Pillow/FFmpeg renderer remains active.
- Remotion is a later spike candidate.
- Pros: React/CSS motion, richer UI animation.
- Risks: Node/React stack, build/deploy complexity.
- Decision: no migration until strategy/review/gates/analytics are stable.

An enum such as `render_backend_candidate = python_motion | remotion_spike_candidate` is acceptable; implementation is not.

## Tests to add

Cover at least:

- bridge conversion produces a `VideoCandidateV2`
- workflow classifies ready/blocked/invalid
- deterministic ReviewPackageV2 JSON
- strict approval parser exact-match behavior
- ScoreV2 not automatically 100
- anti-example required by series
- human_texture_note required
- claim gate blocks sourced/risky claims without source
- AI disclosure unclear blocks
- LinkedIn manual platform fit exists
- demo CLI emits at most 3 candidates

## End-state report

Keep the final report short and implementation-oriented:

- changed files
- pytest result
- whether Sprint-1 commit was created
- whether `demo_review_batch_v2` is usable
- three short example review packages with score/status/approval command
- open points
- next small sprint

Explicitly state that no final videos, no renderings, no platform APIs, no auto-posting, no dashboard, and no mass production were done.