@julioventura/opensquad 0.1.17

package/_opensquad/core/best-practices/run-recovery.md

@@ -0,0 +1,61 @@
+---
+name: "Run Recovery"
+whenToUse: "Interrupted or manually resumed Opensquad runs that need deterministic closure across publishing, newsletter, and dashboard steps."
+---
+
+# Run Recovery Playbook
+
+Use this checklist when a run stops mid-execution, a wrapper command fails, or publication has to continue manually from an existing `squads/{name}/output/{run_id}/` folder.
+
+## Deterministic Checklist
+
+1. Confirm the canonical run folder.
+   Use the same `output/{run_id}` directory for every resumed step. Do not create a second run folder for the same execution.
+
+2. Reconstruct the archived run state before closing anything.
+   Run:
+
+   ```bash
+   node --env-file=.env skills/run-dashboard/scripts/finalize-state.js --workspace-root . --run-dir "squads/{name}/output/{run_id}"
+   ```
+
+   If this step cannot infer a final state yet, continue the missing publish steps first and rerun the command before dashboard closure.
+
+3. Recover Instagram/Facebook deterministically.
+   First rerun `instagram-publisher` with `--dry-run`.
+   If `createChildContainer` fails with transient media errors, retry once with a publish-safe caption: concise body, normalized punctuation, no raw source URLs, hashtags at the end.
+   If Instagram already succeeded but Facebook failed, use `--facebook --facebook-only` instead of reposting Instagram.
+   If the final Instagram `publishMedia` step fails with Meta `code 4`, `error_subcode 2207051`, or `Application request limit reached` after containers were created, stop retrying the Graph API path. Switch to Meta Business Suite with the approved images and caption, using the correct brand login for the target Instagram account/Page.
+   After any manual Meta Business Suite publish, verify the carousel order before finalizing the run. If the order is wrong, republish first. Delete the wrong Instagram post when permissions allow it; treat Facebook deletion as optional because Page permission context may still block cleanup.
+
+4. Recover YouTube deterministically.
+   First rerun `youtube-publisher` with `--dry-run`.
+   If Google returns `invalid_grant`, treat the refresh token as revoked.
+   Generate a fresh consent URL, approve with the correct brand account, capture the `code` from the `127.0.0.1:3000` redirect URL even if the page shows `ERR_CONNECTION_REFUSED`, exchange that code manually for a new refresh token, update `.env`, and rerun the dry-run before the live upload.
+
+5. Finish complementary distribution.
+   If the squad contract includes `jornal-matutino`, run:
+
+   ```bash
+   node --env-file=.env squads/jornal-matutino/scripts/send-from-run.js --workspace-root . --run-dir "squads/{name}/output/{run_id}"
+   ```
+
+6. Regenerate the final dashboard only after the outputs above are complete.
+   Run:
+
+   ```bash
+   node --env-file=.env skills/run-dashboard/scripts/generate.js --workspace-root . --run-dir "squads/{name}/output/{run_id}"
+   ```
+
+   This step must happen after `publish-result.md`, newsletter outputs, and `state.json` are all present.
+   If static dashboard publish is enabled with `transport: ftp` or `transport: both`, confirm the configured `publish_dir_env` resolves and that the FTP env keys declared in `channel-config.yaml` are present before treating the run as closed.
+
+7. Verify closure artifacts.
+   Confirm the run folder contains at minimum:
+   `publish-result.md`, `state.json`, `run-dashboard.html`, `run-dashboard.data.json`, and any expected newsletter files.
+
+## Non-Negotiable Rules
+
+- The runner pipeline document remains the source of truth if a CLI wrapper is incomplete.
+- Do not close a run with dashboard publishing while `state.json` is still missing from the run folder.
+- Do not retry live publishes blindly; always prefer the narrowest dry-run or partial recovery path first.

package/_opensquad/core/best-practices/social-networks-publishing.md

@@ -0,0 +1,327 @@
+---
+id: social-networks-publishing
+name: "Social Networks Publishing"
+whenToUse: |
+  Creating agents that publish content to Instagram, LinkedIn, X/Twitter,
+  YouTube, or other social platforms.
+  NOT for: copywriting, visual design, research, strategic planning.
+version: "1.0.0"
+---
+
+# Social Networks Publishing — Best Practices
+
+## Core Principles
+
+1. **Never publish without explicit user confirmation.** This is the cardinal rule. Before any live post, present the full preview (platform, images, caption, hashtags) and wait for the user to confirm. A dry-run is not confirmation. The user must explicitly say "publish" or "go ahead" before any live API call is made.
+
+2. **Dry-run first, always.** The first execution of any publishing workflow must be a dry-run (test mode). This validates that credentials are configured, images meet requirements, captions are within limits, and the API connection works. Only after a successful dry-run should the user be offered the option to publish for real.
+
+3. **Validate platform requirements before attempting to publish.** Every platform has specific constraints. Validate all of them before making any API call. If validation fails, report the specific issue and suggest a fix before proceeding.
+
+4. **Format content natively for each platform.** The same content may need reformatting for different platforms. Instagram captions use line breaks and 5-8 hashtags at the end. LinkedIn uses professional tone with 1-3 hashtags. X/Twitter needs concise messaging within character limits. Never publish the exact same raw text across all platforms without adaptation.
+
+5. **Report publishing results immediately.** After every publish attempt, report the outcome clearly:
+   - **Success**: Platform, post URL/permalink, post ID, timestamp
+   - **Failure**: Platform, error message, HTTP status code, suggested fix
+   - **Partial success** (multi-platform): Which platforms succeeded and which failed, with details for each
+
+6. **Multi-platform publishing is sequential, not parallel.** When publishing to multiple platforms, publish to one at a time. Report the result of each before proceeding to the next. If one fails, ask the user whether to continue with remaining platforms or stop. Never fire-and-forget across all platforms simultaneously.
+
+7. **Respect rate limits and warn proactively.** Track API usage against known rate limits. If the user is approaching a limit (e.g., 20 of 25 Instagram posts in 24 hours), warn them before the publish attempt, not after the error. Better to prevent a failed publish than to explain why it failed.
+
+8. **Graceful handling of missing skills.** If the user requests publishing to a platform whose skill is not installed, do not error out. Instead: (a) list which platforms ARE available via installed skills, (b) explain which skill would be needed for the requested platform, (c) offer to proceed with available platforms only.
+
+9. **Image format policy must match the active publisher.** In shared Opensquad social/newsletter flows, local slide assets may be JPG/JPEG or PNG. Validate against the active publisher before blocking, and never silently convert or silently fail. If a transformation is required, document it explicitly.
+
+10. **Run dashboard finalization is automatic after the last selected output.** When a publish belongs to an Opensquad run, the run is not operationally complete until `run-dashboard.html` and `run-dashboard.data.json` are regenerated for that run. If the squad config enables static publish, publish the latest and archived snapshots automatically and report the URLs. Do not open a second confirmation step just for the dashboard.
+
+## Platform Requirements
+
+Every platform has specific constraints that must be validated before making any API call.
+
+### Instagram
+
+- **Image format**: JPG/JPEG or PNG
+- **Image count**: 2-10 images for carousel
+- **Caption length**: Max 2,200 characters
+- **Rate limit**: 25 posts per 24 hours
+- **Image hosting**: Use imgBB for public URLs (requires `IMGBB_API_KEY` in `.env`). Get a free key at <https://api.imgbb.com/>.
+- **Multi-brand routing**: In shared workspaces, prefer squad-specific env aliases over generic keys whenever brand-specific variables already exist.
+- **Known live-publish blocker**: If Instagram container creation succeeds but the final `publishMedia` call fails with Meta `code 4`, `error_subcode 2207051`, or `Application request limit reached`, treat it as a Graph API restriction for that app/account pair. Do not keep retrying blindly.
+
+### LinkedIn
+
+- **Image format**: JPG/PNG
+- **Image count**: Max 9 images
+- **Caption length**: 3,000 character limit
+- **Hashtags**: No hashtag walls. Keep to 1-3 relevant hashtags.
+
+### X/Twitter
+
+- **Image format**: JPG/PNG/GIF
+- **Image count**: Max 4 images
+- **Caption length**: 280 characters (or 25,000 for long-form)
+
+### TikTok
+
+- **Content type**: Video only for posts
+- **Aspect ratios**: Platform-specific aspect ratios required
+
+### YouTube
+
+- **Thumbnail format**: JPG/JPEG or PNG
+- **Thumbnail size**: Max 2MB
+- **Thumbnail dimensions**: 1280x720 minimum
+- **Local dependency**: `ffmpeg` installed and callable from the same shell used for the publish command
+- **Canonical slideshow assembly**: All YouTube slideshow videos must follow the standard defined in `_opensquad/core/defaults/youtube-video-assembly.json`. Key rules:
+  - Transition: `fadeblack`, 2 seconds, visual starts **after** the full slide narration block ends (never overlapping narration)
+  - Slide timing formula: `1s lead-in + title narration + 1s pause + text narration + 2s tail + 1s buffer`
+  - Middle slides get 2× `transitionDuration` as effective input duration (required by xfade for simultaneous in/out frames)
+  - Audio mix: always use `amix` with `normalize=0` to prevent volume jump on last slide when SFX ends before narration
+  - Transition SFX: reuse `public/sfx/slide-transition-sfx.mp3` (warm whoosh); do NOT regenerate per run
+  - Background music volume with voice: `0.12`; narration volume: `1.2`
+
+## Publishing Workflow
+
+- **Receive content and identify targets.** Receive the approved content (images and text) from upstream agents or the user. Identify the target platform(s) for publication. If the user has not specified platforms, ask before proceeding.
+
+- **Check skill availability.** For each target platform, verify that the required publishing skill is installed:
+  - Instagram: `instagram-publisher` skill
+  - Multi-platform (LinkedIn, X, TikTok, etc.): `blotato` skill
+  - If a required skill is missing, inform the user and list alternatives.
+
+- **Validate content against platform requirements.** For each target platform, check:
+  - Image format and count against the active publisher constraints (in the shared Opensquad flow, slides may arrive as JPG/JPEG or PNG)
+  - Caption length against character limit
+  - Aspect ratio compatibility
+  - Required local tools for the active publisher (for YouTube, validate `ffmpeg -version` before dry-run)
+  - Any platform-specific restrictions
+  - If validation fails, report the specific issue and suggest a fix before proceeding.
+
+- **Present preview to user.** Show a clear, structured preview:
+
+  ```text
+  PUBLISH PREVIEW
+  Platform: Instagram (carousel)
+  Images: 7 slides (slide-01.jpg through slide-07.jpg)
+  Caption: [first 200 chars]... (1,847 / 2,200 chars)
+  Hashtags: #marketing #contentcreation #socialmedia (3)
+  Status: All validations passed
+  ```
+
+- **Execute dry-run.** Run the publishing workflow in test mode:
+  - Instagram: `--dry-run` flag on the publish script
+  - YouTube: validate `ffmpeg -version` in the current shell, then run the publish script with `--dry-run`
+  - Blotato: validate API connection and media upload without posting
+  - Report dry-run results: credentials OK, media uploaded, container created, ready to publish.
+
+- **Request final confirmation.** Present the dry-run results and ask the user to confirm the live publish. Do not proceed without explicit approval.
+
+- **Publish and report.** Execute the live publish. Report the result immediately:
+  - Success: post URL, post ID, platform, timestamp
+  - Failure: error details, suggested fix, option to retry
+
+- **Use a UI/Browser fallback when the API path is blocked.** If the Instagram Graph API dry-run or container creation succeeds but the live `publishMedia` step is blocked by the known Meta restriction above (such as rate limits or app-review requirement), switch to the automated Playwright browser fallback script (`publish-playwright.js`). If that automation is not available or encounters issues, perform a manual publish via Meta Business Suite using the same approved assets and caption. Always use the correct brand login for the target account/page.
+
+- **Automated Browser (Playwright) Fallback Best Practices:**
+  - **Selector Behavior (Visibility vs. Attachment):** In the Instagram web interface, the file upload input element (`<input type="file">`) is styled with `display: none` and is permanently hidden. Consequently, a standard Playwright `waitForSelector('input[type="file"]')` will time out because it waits for visibility. You **must** specify `{ state: 'attached' }` to target this element correctly.
+  - **Click Event Bubbling:** Clicking a standard text span like `span:has-text("Criar")` directly might not bubble up to trigger the creation popup. Target the parent anchor link `a:has-text("Criar")` or a button container `div[role="button"]` instead.
+  - **Persistent Profile & Headful Execution:** Always run browser-based fallback publishing in headful mode (`headless: false`) and load the persistent user data directory (`_opensquad/_browser_profile`). This allows reusing authenticated sessions/cookies and allows the user to complete 2FA or click manually if any interface element changes.
+
+- **Validate carousel order before finalizing.** In any manual or browser-automated publish flow, explicitly confirm that slide 1 is the cover and that the remaining slides stayed in the approved order before you treat the run as complete. If the order is wrong, republish before regenerating dashboards or reporting final URLs.
+
+- **Finalize the run dashboard automatically.** After the last selected output succeeds, regenerate the run dashboard for the same run folder. If `jornal-matutino` is still pending, wait and do this only after the newsletter step completes. If the squad config enables static publish, let the dashboard step publish automatically and report the local files plus the public URL(s).
+
+- **Multi-platform: repeat per platform.** If publishing to multiple platforms, repeat the validation, dry-run, confirmation, and live publish sequence for each platform sequentially. Report results after each one.
+
+## Decision Criteria
+
+- **Which skill to use**: Instagram-only content uses `instagram-publisher` (direct API, most control). Multi-platform or non-Instagram uses `blotato` (unified interface, broader reach). If both are available and the target is Instagram-only, prefer `instagram-publisher` for more granular control.
+- **When to convert image formats**: Convert only when the target skill or pipeline truly requires a different format and the user approves the transformation. If the current shared flow already accepts JPG/JPEG and PNG, do not block solely because the slides are PNG.
+- **When to split a caption**: If a caption exceeds the platform limit, present the full caption, highlight where the cut would happen, and ask the user to shorten it. Do not truncate automatically.
+- **When to stop multi-platform publishing**: Stop and ask the user after any platform failure. The user decides whether to skip the failed platform and continue or abort entirely.
+
+## Quality Criteria
+
+- [ ] User confirmation was received before any live publish (not just dry-run)
+- [ ] Dry-run was executed and passed before live publish
+- [ ] All platform-specific validations passed (image format, dimensions, caption length, image count)
+- [ ] Publish preview was presented with complete details (platform, images, caption, validation status)
+- [ ] Successful publishes include post URL/permalink and post ID
+- [ ] Failed publishes include error details, HTTP status, and suggested fix
+- [ ] Multi-platform publishing was executed sequentially with per-platform reporting
+- [ ] Rate limit status was checked and reported before publishing
+- [ ] No caption was silently truncated or modified without user approval
+- [ ] `run-dashboard.html` and `run-dashboard.data.json` were regenerated after the last selected output
+- [ ] If the squad config enables static publish, the latest and archived `run-dashboard` snapshots were published and reported without a second approval prompt
+
+## Output Examples
+
+### Example 1: Instagram Carousel Publish Workflow
+
+```text
+PUBLISH PREVIEW
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Platform:  Instagram (carousel)
+Account:   @brandname
+Skill:     instagram-publisher
+Images:    7 slides
+  1. slide-01.jpg (1080x1440, JPEG, 287KB)
+  2. slide-02.jpg (1080x1440, JPEG, 195KB)
+  3. slide-03.jpg (1080x1440, JPEG, 213KB)
+  4. slide-04.jpg (1080x1440, JPEG, 178KB)
+  5. slide-05.jpg (1080x1440, JPEG, 201KB)
+  6. slide-06.jpg (1080x1440, JPEG, 192KB)
+  7. slide-07.jpg (1080x1440, JPEG, 244KB)
+
+Caption (1,847 / 2,200 chars):
+  "You are doing 100 things to grow on Instagram.
+   And ignoring the ONE that actually works.
+
+   Here is what nobody tells you about organic growth:
+   [... truncated for preview ...]
+
+   Comment GUIDE below and I will DM you the full playbook.
+
+   #instagramgrowth #socialmedia #contentcreator
+   #digitalmarketing #organicgrowth"
+
+VALIDATION
+  Image format: JPEG (required: JPEG)
+  Image count: 7 (required: 2-10)
+  Image dimensions: 1080x1440 (valid carousel)
+  Caption length: 1,847 chars (max: 2,200)
+  Hashtags: 5 (recommended: 5-8)
+  Rate limit: 3/25 posts used in last 24h
+
+Status: All validations passed. Ready for dry-run.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+DRY-RUN RESULT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Credentials: Valid (token expires 2026-04-15)
+  Image upload: 7/7 images uploaded to imgBB
+  Media containers: 7/7 containers created
+  Carousel container: Created successfully
+  Publish: Skipped (dry-run mode)
+
+Dry-run passed. Awaiting confirmation to publish live.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+PUBLISH RESULT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Published successfully
+  Platform:  Instagram
+  Post URL:  https://www.instagram.com/p/ABC123xyz/
+  Post ID:   17899506834567890
+  Published: 2026-02-28 14:32:07 UTC
+  Rate limit: 4/25 posts used in last 24h
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Example 2: Multi-platform Publish with Partial Failure
+
+```text
+MULTI-PLATFORM PUBLISH
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Targets: Instagram, LinkedIn, X/Twitter
+Skill:   blotato (multi-platform)
+
+PLATFORM 1/3: Instagram
+  Validation: All checks passed
+  Dry-run:    Passed
+  Publish:    Published successfully
+  Post URL:   https://www.instagram.com/p/DEF456abc/
+  Post ID:    ig_17899506834567890
+  Published:  2026-02-28 14:35:12 UTC
+
+PLATFORM 2/3: LinkedIn
+  Validation: All checks passed
+  Dry-run:    Passed
+  Publish:    FAILED
+  Error:      403 Forbidden — "Publishing permission not granted"
+  HTTP Status: 403
+  Suggested fix: The LinkedIn account may need re-authorization in Blotato.
+    1. Go to Blotato Settings > Connected Accounts
+    2. Disconnect and reconnect the LinkedIn account
+    3. Ensure "Create posts" permission is granted during OAuth
+
+  LinkedIn publish failed. Continue with remaining platforms?
+
+  [User confirms: continue]
+
+PLATFORM 3/3: X/Twitter
+  Validation: Caption exceeds 280 chars (1,847 chars)
+    Original caption is too long for X/Twitter.
+    Options:
+    a) Use the first 277 chars + "..."
+    b) Provide a custom short caption for X/Twitter
+    c) Skip X/Twitter
+
+  [User chooses: b, provides short caption]
+
+  Validation: All checks passed (short caption: 142 chars)
+  Dry-run:    Passed
+  Publish:    Published successfully
+  Post URL:   https://x.com/brandname/status/1234567890123456789
+  Post ID:    tw_1234567890123456789
+  Published:  2026-02-28 14:38:45 UTC
+
+SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Instagram:  Published
+  LinkedIn:   Failed (403 — re-authorize account)
+  X/Twitter:  Published (with custom short caption)
+
+  2/3 platforms published successfully.
+  Action needed: Re-authorize LinkedIn account in Blotato.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Anti-Patterns
+
+### Never Do
+
+1. **Never publish without explicit user confirmation.** Dry-run success is not permission to go live. The user must explicitly confirm every publish. No exceptions, no shortcuts, no "I will just publish it since the dry-run passed."
+
+2. **Never silently truncate captions.** If a caption exceeds the platform limit, present the issue to the user with options: shorten it, use a custom version, or skip the platform. Automatic truncation destroys the copy's structure and CTA.
+
+3. **Never fire-and-forget across multiple platforms.** Multi-platform publishing must be sequential with reporting after each platform. If one fails, the user decides the next step. Parallel publishing hides failures and removes user control.
+
+4. **Never ignore validation failures.** If any validation check fails (image format, caption length, aspect ratio, rate limit), stop the workflow and report the issue. Do not attempt to publish and "see what happens."
+
+5. **Never report success without a URL.** "Published successfully" without a post URL is not verifiable. Every successful publish must include the post permalink. If the API does not return a URL, report that as a limitation.
+
+6. **Never assume credentials are valid.** Always verify credentials during the dry-run phase. Tokens expire, permissions get revoked, accounts get disconnected. A credential check is part of every publish workflow.
+
+7. **Never publish the same raw caption across all platforms without adaptation.** Instagram, LinkedIn, and X/Twitter have different formatting conventions, character limits, and audience expectations. At minimum, verify the caption fits the platform constraints. Ideally, suggest platform-specific adaptations.
+
+### Always Do
+
+1. **Present a structured preview before every publish.** Show: platform, account, images (with dimensions and format), caption (with character count), hashtags, and validation status. The user must see exactly what will be published.
+
+2. **Run a dry-run before every live publish.** Test the full workflow without posting. Verify credentials, upload media, create containers, validate everything. Report dry-run results before requesting confirmation.
+
+3. **Report results immediately after each publish.** Do not batch results. After each platform publish (success or failure), report the outcome with all relevant details before moving to the next platform.
+
+4. **Warn about rate limits proactively.** Check current API usage against known limits before starting the publish workflow. "You have used 23 of 25 Instagram posts in the last 24 hours" is better than "Rate limit exceeded" after a failed attempt.
+
+## Vocabulary Guidance
+
+### Use
+
+- **"Publish preview"** — Always present a structured preview before any publish action. Use this exact header.
+- **"Dry-run result"** — Report test outcomes with this label. Clear distinction from live publishes.
+- **"Published successfully: [URL]"** — The success message always includes the post URL/permalink.
+- **"Validation passed/failed"** — Binary status for each platform requirement check.
+- **"Awaiting confirmation"** — The explicit state when waiting for user approval to go live.
+- **"Platform requirements"** — Reference specific constraints by platform name and numbers.
+- **"Rate limit: X/Y used"** — Proactive reporting of API usage against limits.
+
+### Avoid
+
+- **"I will go ahead and publish"** — Never announce publishing without having received explicit confirmation first.
+- **"Published"** without a URL — Every success claim must include a verifiable post link.
+- **"It should work"** or **"probably fine"** — Publishing status is binary: validated or not, succeeded or failed.
+- **"Oops"** or casual language for failures — Publish failures are serious. Report them professionally with error details and next steps.
+- **Em dashes** — Use periods, colons, or line breaks instead.

package/_opensquad/core/best-practices/squad-creation-checklist.md

@@ -0,0 +1,32 @@
+# Squad Creation Checklist
+
+Default structural contract for every new squad.
+
+Use this checklist to avoid squads that are locally plausible but globally incoherent.
+
+## Checklist
+
+1. Define each pipeline step as a contract, not just a task.
+   Every step must make explicit what it reads, what it writes, how success is judged, and what blocks approval.
+
+2. Bound research before deepening.
+   Research steps should cap the initial scan, use summaries and snippets to filter, and only open full materials when they are necessary to support the brief.
+
+3. Specify the primary deliverable with the right amount of elasticity.
+   If the output can vary in size, count, or length, express that as a clear minimum and maximum instead of hiding a fixed assumption inside examples or downstream steps.
+
+4. Propagate the same deliverable contract end to end.
+   If a squad works with a range such as 2 to 4 slides, the same contract must appear consistently in planning, drafting, visual direction, rendering, preview, publication, examples, and quality criteria.
+
+5. Put a human checkpoint before irreversible execution.
+   Any step that renders, publishes, sends, posts, or otherwise performs a costly or irreversible action must have an approval checkpoint immediately before it.
+
+6. Close with a coherence sweep.
+   Before the squad is considered finished, search the canonical files for stale assumptions, superseded counts, and contract mismatches so the delivered squad matches its intended behavior.
+
+## Quick Heuristics
+
+- Prefer a bounded range over an arbitrary fixed count when the narrative or output size can legitimately vary.
+- Prefer one clear primary deliverable contract over multiple conflicting local assumptions.
+- Prefer cheap filtering before expensive research reads.
+- Prefer one final coherence pass over trusting that earlier edits propagated correctly.