Skip to content

docs(skills): name the media-treatment policy targets instead of alluding to them - #2879

Merged
miguel-heygen merged 1 commit into
mainfrom
docs/skills-name-media-policy-targets
Jul 29, 2026
Merged

docs(skills): name the media-treatment policy targets instead of alluding to them#2879
miguel-heygen merged 1 commit into
mainfrom
docs/skills-name-media-policy-targets

Conversation

@miguel-heygen

@miguel-heygen miguel-heygen commented Jul 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

What

Two agent-facing routing surfaces told agents to follow a media "policy" or "contracts" without naming a resolvable file. This names the files as paths, and scopes the media-treatment policy to what it actually governs.

  • skills/hyperframes/SKILL.md — "Load its media-treatment policy before editing" now reads "Read ../media-use/references/media-treatments.md before editing a treatment; it governs how footage is treated, never whether media may be used."
  • skills/general-video/SKILL.md — "follow its adoption, resolution, provider, provenance, and reuse contracts" now names ../media-use/references/resolve.md and ../media-use/references/setup-providers.md. Drops "provenance": it appears once in references/operations.md as ledger bookkeeping, not as a contract an agent can follow.
  • packages/cli/src/templates/_shared/CLAUDE.md and AGENTS.md carried the same unnamed pointer and ship into every hyperframes init project. Both updated, kept byte-identical.
  • skills-manifest.json regenerated by the pre-commit hook.

Paths use the ../<skill>/references/<file>.md form already used 16 times across skills/*/SKILL.md, so they resolve from the file that contains them. The existing `/skill` → `references/x.md` arrow convention elsewhere in general-video/SKILL.md is left alone; it names its owning skill and is not the defect here.

Why

From a real Codex session log building an outro from a customer's own site.

  1. The agent reads skills/hyperframes/SKILL.md, which at the time said "Load its media-treatment policy before editing."
  2. Four log entries later it announces: "The Hyperframes media policy applies here because we're replacing an invented graphic with real site media. I'm checking the page's asset delivery and licensing metadata."
  3. It goes looking for that policy in /media-use, opens SKILL.md and references/operations.md, neither of which contains the word "policy", and never opens references/media-treatments.md, where it lives.
  4. Finding nothing, it improvises a licensing gate. No licensing rule exists anywhere in the skills; searching every tool output in the session for "licens" returns zero hits.
  5. The user reads that, concludes the framework is blocking them from using their own assets, and moves the deliverable to another framework.

Nothing was ever actually blocked, the agent downloaded and used the asset seconds later. An unnamed "policy" was enough for a model to invent its contents and for a user to believe it. The skill files involved were byte-identical to main, so this is not a stale-install problem.

How

Name the target file, as a path that resolves, at every point the routing surface refers to a policy or contract. Say what the media-treatment policy is not about. Both are the same defect: a pointer an agent cannot follow becomes a rule an agent makes up.

Scope is deliberately limited to unnamed policy/contract pointers.

Test plan

  • bunx vitest run src/commands/coreSkillContent.test.ts src/commands/figma/skillContent.test.ts in packages/cli — 15 passed. coreSkillContent.test.ts asserts the media-treatment discovery gate is present in both templates; the three strings it checks are preserved.

  • Resolved every backticked path-like .md reference in both changed skill files from that file's own directory: skills/hyperframes/SKILL.md has zero unresolved. In skills/general-video/SKILL.md the three paths this PR touches resolve; the 12 that remain unresolved by literal path are the pre-existing arrow-convention refs, each preceded by its owning skill, and are untouched.

  • Verified packages/cli/src/templates/_shared/CLAUDE.md and AGENTS.md are still byte-identical.

  • Verified zero occurrences of "media-treatment policy" remain in the repo.

  • Unit tests added/updated

  • Manual testing performed

  • Documentation updated (if applicable)

@miguel-heygen
docs(skills): name the media-treatment policy targets instead of allu…
e453cf3 
…ding to them

Two routing surfaces pointed agents at media "policies" and "contracts" without
naming a file. An agent that goes looking and finds nothing fills the gap with
an invented rule.

- skills/hyperframes/SKILL.md: "Load its media-treatment policy" now names
  references/media-treatments.md and states the policy governs how footage is
  treated, never whether media may be used.
- skills/general-video/SKILL.md: "adoption, resolution, provider, provenance,
  and reuse contracts" now names references/resolve.md and
  references/setup-providers.md. Drops "provenance", which is ledger
  bookkeeping in operations.md, not a contract to follow.
- The scaffolded project templates carried the same unnamed pointer and ship to
  every hyperframes init; both updated and kept byte-identical.
@miguel-heygen
miguel-heygen force-pushed the docs/skills-name-media-policy-targets branch from ac01e8a to e453cf3 Compare July 29, 2026 15:19
vanceingalls
vanceingalls approved these changes Jul 29, 2026
View reviewed changes

@vanceingalls vanceingalls left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Grade: A — verified at head e453cf3e

Verified claims

  1. Four unnamed-pointer sites updated with resolvable paths. skills/hyperframes/SKILL.md L99-107 and skills/general-video/SKILL.md L23 both now name the target file as a ../media-use/references/<file>.md path that resolves from the file that contains it — target files present at HEAD (media-treatments.md, resolve.md, setup-providers.md).
  2. Zero occurrences of media-treatment policy remain in any of the four touched files at HEAD SHA (verified via file-contents grep).
  3. Template parity preserved. packages/cli/src/templates/_shared/CLAUDE.md and .../AGENTS.md share the same git blob SHA 6b10521743a7fb44512a6eb780a5936c852e01f2 at HEAD (both 7133 bytes) → byte-identical after both received the same one-line change.
  4. Scope disclaimer ("It governs how footage is treated, never whether media may be used") is applied to the three surfaces where the observed hallucination originated (routing SKILL.md + both templates); it's the specific counter-message to the "agent invented a licensing gate" failure mode described in the session log. skills/general-video/SKILL.md change is path-naming only, which reads correct — the entry to general-video is already in-domain, so the disclaimer's need doesn't repeat there.
  5. "Drops provenance" is defensible. The word appears in references/operations.md:60 as ledger bookkeeping ("it records provenance and auto-promotes"), in resolve.md:106 as disk-artifact description ("candidates, scores, provenance stay on disk"), and in media-treatment-recipes.md:433 as a treatment consideration ("false provenance"). None of these is a contract an agent can load, so removing "provenance" from the routing-surface pointer is right-shaped.
  6. skills-manifest.json hash-only regen for general-video (87f2 → 49f5) and hyperframes (02b4 → db16) — matches the two SKILL.md changes; other entries untouched.

Root-cause fit

The PR body's session-log trace is the correct diagnosis: an unnamed "policy" pointer → the agent looks for it in the wrong location → improvises a licensing gate → user believes it. Fix is minimal (name the file as a resolvable path; add the "governs treatment, not use" scope) and matches the observed defect surface. The scope disclaimer directly counters the specific hallucination axis (licensing/use-permission) that showed up in the shared session.

No findings

Diff scope is deliberately minimal; every changed line is warranted. Approving.

— Review by Via

james-russo-rames-d-jusso
james-russo-rames-d-jusso reviewed Jul 29, 2026
View reviewed changes

@james-russo-rames-d-jusso james-russo-rames-d-jusso left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at e453cf3.

Traced the JSONL against the fix. The failure mode had two components and this PR closes both:

  1. Wrong destination. The agent went to /media-use, opened SKILL.md + references/operations.md, and never opened references/media-treatments.md — because the pointer that sent it there ("media-treatment policy") was not a resolvable filename. The new wording names ../media-use/references/media-treatments.md directly, using the same ../<skill>/references/<file>.md form already established 16× elsewhere across skills/*/SKILL.md.
  2. Licensing-gate hallucination. The agent inflated "media-treatment policy" into a "media policy" that governs whether real footage may be used, then went hunting for asset-delivery/licensing metadata that doesn't exist in the framework. The added "it governs how footage is treated, never whether media may be used" is exactly the negative scope needed — and it matches the target file's own opening ("Permission and scope" section discusses whether-to-apply-a-treatment, never whether-media-may-be-used).

Also spot-checked:

  • Cross-repo sweep clean. heygen-com/hyperframes-internal origin/main has zero occurrences of "media-treatment policy" or "media policy" — no half-migrated pointer left in the sidecar.
  • Sibling skill files clean. Grepped every skills/*/*.md under this repo at head: the remaining "policy" occurrences are unrelated body text (autoplay-policy, "policy statements" as monotone-content example, an in-fixture quote about USD policy) — no other unnamed routing pointer.
  • Templates stayed byte-identical. packages/cli/src/templates/_shared/{CLAUDE,AGENTS}.md still match (diff -q → identical), preserving the invariant coreSkillContent.test.ts relies on.
  • Manifest hashes recompute cleanly. general-video and hyperframes are the only two entries that changed in skills-manifest.json, matching the two SKILL.md edits; "Skills: manifest in sync" CI check is green.
  • Test-plan preservation intact. The three anchor strings coreSkillContent.test.ts asserts (/media-use, media-treatments, "seek-safe motion") all survive the new wording.
  • The "provenance" drop from general-video/SKILL.md is well-scoped. Per the PR body, "provenance" appeared once as ledger bookkeeping in references/operations.md, not as an agent-followable contract — grepping confirms every other provenance occurrence is either Figma-specific (.media/manifest.jsonl provenance) or .media/ inventory bookkeeping, i.e. not a routing surface an agent would go looking for as a "contract" to follow.

The "name-a-resolvable-path AND state what the doc is-not-about" pattern is worth carrying forward whenever a routing surface points at a policy or contract — it closes both the wrong-destination class AND the invented-scope class in one line. No changes requested.

— Review by Rames D Jusso

@miguel-heygen
miguel-heygen merged commit 6cab53a into main Jul 29, 2026
44 of 73 checks passed
@miguel-heygen
miguel-heygen deleted the docs/skills-name-media-policy-targets branch July 29, 2026 15:27
dahans-msft2 pushed a commit to dahans-msft2/hyperframes that referenced this pull request Aug 6, 2026
@miguel-heygen
docs(skills): name the media-treatment policy targets instead of allu…
3ca599b 
…ding to them (heygen-com#2879)

Two routing surfaces pointed agents at media "policies" and "contracts" without
naming a file. An agent that goes looking and finds nothing fills the gap with
an invented rule.

- skills/hyperframes/SKILL.md: "Load its media-treatment policy" now names
  references/media-treatments.md and states the policy governs how footage is
  treated, never whether media may be used.
- skills/general-video/SKILL.md: "adoption, resolution, provider, provenance,
  and reuse contracts" now names references/resolve.md and
  references/setup-providers.md. Drops "provenance", which is ledger
  bookkeeping in operations.md, not a contract to follow.
- The scaffolded project templates carried the same unnamed pointer and ship to
  every hyperframes init; both updated and kept byte-identical.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@james-russo-rames-d-jusso james-russo-rames-d-jusso james-russo-rames-d-jusso left review comments
@vanceingalls vanceingalls vanceingalls approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@miguel-heygen @vanceingalls @james-russo-rames-d-jusso