fix(skills): recipe freeze reads workflow from BRIEF.md; style_preset records require workflow scope

Two holes found by a live companion-run freeze: the agent-supplied --workflow
contradicted the run's actual workflow (recipe.json said faceless-explainer,
brief-skeleton said general-video), and the style_preset lookup missed because
the preference had been recorded under the bare key.

- freezeRecipe resolves the workflow from BRIEF.md frontmatter; the flag is a
  fallback for briefless projects and a contradicting flag is ignored (noted).
- recordPreference refuses a bare style_preset — the scoped key is the only
  writable shape; freeze tolerates legacy bare records via read fallback.
- review-loop § 4 / media-use SKILL / brief-format wording follow the machinery.

Author: WaterrrForever

skills-manifest.json

@@ -30,7 +30,7 @@
       "files": 11
     },
     "hyperframes-core": {
-      "hash": "1e5f886e4b9971b0",
+      "hash": "cf6e9f7827bc86d1",
       "files": 17
     },
     "hyperframes-creative": {
@@ -46,7 +46,7 @@
       "files": 10
     },
     "media-use": {
-      "hash": "9a4f585129692a22",
+      "hash": "5bb2cf3a97d0b09c",
       "files": 130
     },
     "motion-graphics": {

skills/hyperframes-core/references/brief-format.md

@@ -16,7 +16,7 @@ YAML block at the top: one key per deterministic field — the run's shape first
 | `message`                                                                 | the ONE thing the video must communicate                                                                                   | `"Ship it in an afternoon"` |
 | `destination` / `aspect` / `language` / `audience` / `length` / `angle` … | the registry fields this route confirmed                                                                                   | —                           |
 
-**Which keys are memory.** Only the preference-backed subset — `destination`, `aspect`, `language`, `flow`, `storyboard`, `voice`, `style_preset` — is recorded with `media-use` → `scripts/prefs.mjs record` (the store rejects any other key). `message`, `audience`, `length`, `angle` live in the frontmatter only: they describe this video, not the user.
+**Which keys are memory.** Only the preference-backed subset — `destination`, `aspect`, `language`, `flow`, `storyboard`, `voice`, `style_preset` — is recorded with `media-use` → `scripts/prefs.mjs record` (the store rejects any other key). `style_preset` is stored per workflow: record it with `--workflow <w>` (the store refuses it bare — a look confirmed for one genre is not a default for the others). `message`, `audience`, `length`, `angle` live in the frontmatter only: they describe this video, not the user.
 
 ## Body — the intent in prose
 

skills/hyperframes-core/references/review-loop.md

@@ -38,4 +38,4 @@ Mark each frame `animated` as it lands. The build gate carries the loop's condit
 
 After the workflow's checks pass, use the **final composition preview**. In collaborative mode Studio may already be serving from § 1; hand the timeline URL and ask one thing: render now, or what changes? In autonomous mode this is the one question the mode keeps: ask “preview first, or render?” Open the final preview on yes; render on an explicit render answer. Render only on approval.
 
-**After approval, offer the recipe — once.** An approved run is a proven bundle. At delivery, offer to freeze it: `media-use` → `scripts/recipe.mjs freeze --name <name> --workflow <workflow>` keeps the design spec, the storyboard skeleton (structure kept, content blanked), the brief skeleton, and the confirmed brief values, and the next run of this type starts from it (the intent layer checks for a matching recipe before its first question). When the freeze lands, teach the recall in the confirmation — "Saved as **<name>** (v<N>). Next time say _make another <name>_, or just _like last time_." — the name is something the system reminds the user of, never something they must remember. In autonomous mode don't ask — name the freeze command in the delivery note instead.
+**After approval, offer the recipe — once.** An approved run is a proven bundle. At delivery, offer to freeze it: `media-use` → `scripts/recipe.mjs freeze --name <name>` (the workflow comes from BRIEF.md; pass `--workflow` only in a project without one) keeps the design spec, the storyboard skeleton (structure kept, content blanked), the brief skeleton, and the confirmed brief values, and the next run of this type starts from it (the intent layer checks for a matching recipe before its first question). When the freeze lands, teach the recall in the confirmation — "Saved as **<name>** (v<N>). Next time say _make another <name>_, or just _like last time_." — the name is something the system reminds the user of, never something they must remember. In autonomous mode don't ask — name the freeze command in the delivery note instead.

skills/media-use/SKILL.md

@@ -335,7 +335,7 @@ Only what the user actually confirmed gets recorded — never an inferred or def
 The heavyweight tier of user memory: one approved run frozen as a named, versioned bundle — `frame.md`, the storyboard skeleton (structure kept, content blanked to per-frame fill-ins), the brief skeleton (from `BRIEF.md` when the project has one — reusable frontmatter kept, run-shape and prose blanked), and the confirmed brief values. Same two tiers: project `.media/recipes/<name>/` (committed) and `~/.media/recipes/<name>/` (a freeze is already a confirmed bundle, so it promotes immediately — no two-project rule). Re-freezing a name bumps `version` and archives the old folder as `<name>@v<N>`.
 
 ```bash
-node <SKILL_DIR>/scripts/recipe.mjs freeze --hyperframes . --name weekly-promo --workflow product-launch-video
+node <SKILL_DIR>/scripts/recipe.mjs freeze --hyperframes . --name weekly-promo   # workflow read from BRIEF.md (--workflow only for briefless projects)
 node <SKILL_DIR>/scripts/recipe.mjs list --hyperframes . --workflow product-launch-video
 node <SKILL_DIR>/scripts/recipe.mjs use --hyperframes . --name weekly-promo   # also: resolve.mjs --type recipe --entity weekly-promo
 ```

skills/media-use/scripts/lib/prefs-store.mjs

@@ -158,6 +158,9 @@ export function recordPreference({ projectDir, key, value, workflow }) {
   if (typeof value !== "string" || !value.trim()) {
     throw new Error("a preference needs a non-empty string value");
   }
+  if (key === "style_preset" && (!workflow || !String(workflow).trim())) {
+    throw new Error("style_preset is stored per workflow — pass --workflow <w>");
+  }
   const fullKey = preferenceKeyFor(key, workflow);
   const projectName = basename(resolve(projectDir));
   const trimmed = value.trim();

skills/media-use/scripts/lib/prefs-store.test.mjs

@@ -159,6 +159,16 @@ test("style_preset is keyed per workflow", () => {
   });
 });
 
+test("style_preset without a workflow is rejected, never stored bare", () => {
+  withSandbox(({ projectA }) => {
+    assert.throws(
+      () => recordPreference({ projectDir: projectA, key: "style_preset", value: "pin-and-paper" }),
+      /pass --workflow/,
+    );
+    assert.deepEqual(mergedPreferences(projectA), {});
+  });
+});
+
 test("unknown keys and empty values are rejected", () => {
   withSandbox(({ projectA }) => {
     assert.throws(() => recordPreference({ projectDir: projectA, key: "vibe", value: "x" }));

skills/media-use/scripts/lib/recipe-store.mjs

@@ -167,6 +167,20 @@ export function skeletonizeStoryboard(source) {
   return out.join("\n").replace(/\n{3,}/g, "\n\n");
 }
 
+/** The run's workflow as BRIEF.md records it — the source of truth a freeze
+ * must not contradict. Undefined when no BRIEF.md (or no `workflow:`) exists. */
+function briefWorkflow(root) {
+  const brief = join(root, "BRIEF.md");
+  if (!existsSync(brief)) return undefined;
+  const lines = readFileSync(brief, "utf8").split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") return undefined;
+  for (let i = 1; i < lines.length && lines[i].trim() !== "---"; i++) {
+    const match = lines[i].match(/^workflow\s*:\s*(.+?)\s*$/);
+    if (match) return match[1].replace(/^["']|["']$/g, "") || undefined;
+  }
+  return undefined;
+}
+
 function readRecipeJson(dir) {
   try {
     const parsed = JSON.parse(readFileSync(join(dir, "recipe.json"), "utf8"));
@@ -189,9 +203,15 @@ function prefValue(prefs, key) {
  * freeze is already confirmed — it promotes immediately).
  */
 export function freezeRecipe({ projectDir, name, workflow, blocks }) {
-  if (!workflow || !String(workflow).trim()) throw new Error("freeze needs --workflow");
   const slug = slugifyRecipeName(name);
   const root = resolve(projectDir);
+  const fromBrief = briefWorkflow(root);
+  const fromFlag = workflow && String(workflow).trim() ? String(workflow).trim() : undefined;
+  // BRIEF.md decides; the flag only covers projects briefed before it existed.
+  const resolvedWorkflow = fromBrief ?? fromFlag;
+  if (!resolvedWorkflow) {
+    throw new Error("no workflow found — BRIEF.md names none and no --workflow was given");
+  }
   const frameSpec = join(root, "frame.md");
   const storyboard = join(root, "STORYBOARD.md");
   if (!existsSync(frameSpec)) throw new Error("no frame.md to freeze — run the design step first");
@@ -212,14 +232,17 @@ export function freezeRecipe({ projectDir, name, workflow, blocks }) {
   const recipe = {
     version,
     name: slug,
-    workflow: String(workflow).trim(),
+    workflow: resolvedWorkflow,
     approved_at: new Date().toISOString(),
     source_project: basename(root),
     destination: prefValue(prefs, "destination"),
     aspect: prefValue(prefs, "aspect"),
     language: prefValue(prefs, "language"),
     voice: prefValue(prefs, "voice"),
-    style_preset: prefValue(prefs, `style_preset.${String(workflow).trim()}`),
+    // The bare-key fallback tolerates records made before the store required
+    // style_preset to be workflow-scoped.
+    style_preset:
+      prefValue(prefs, `style_preset.${resolvedWorkflow}`) ?? prefValue(prefs, "style_preset"),
     blocks: Array.isArray(blocks) && blocks.length > 0 ? blocks : undefined,
   };
 
@@ -261,7 +284,15 @@ export function freezeRecipe({ projectDir, name, workflow, blocks }) {
     // The project-tier freeze already landed.
   }
 
-  return { id, slug, version, dir, briefSkeleton };
+  return {
+    id,
+    slug,
+    version,
+    dir,
+    briefSkeleton,
+    workflow: resolvedWorkflow,
+    workflowOverridden: Boolean(fromBrief && fromFlag && fromBrief !== fromFlag),
+  };
 }
 
 function scanRecipesDir(dir, source) {

skills/media-use/scripts/lib/recipe-store.test.mjs

@@ -229,6 +229,78 @@ test("freeze without a BRIEF.md degrades: no skeleton, use returns no path", ()
   });
 });
 
+test("freeze takes the workflow from BRIEF.md over a contradicting flag", () => {
+  withSandbox(({ project }) => {
+    writeFileSync(
+      join(project, "BRIEF.md"),
+      BRIEF.replace("workflow: product-launch-video", "workflow: general-video"),
+    );
+    const frozen = freezeRecipe({
+      projectDir: project,
+      name: "promo",
+      workflow: "faceless-explainer",
+    });
+    assert.equal(frozen.workflow, "general-video");
+    assert.equal(frozen.workflowOverridden, true);
+    const recipe = JSON.parse(
+      readFileSync(join(project, ".media/recipes/promo/recipe.json"), "utf8"),
+    );
+    assert.equal(recipe.workflow, "general-video");
+  });
+});
+
+test("freeze without BRIEF.md falls back to --workflow; with neither it refuses", () => {
+  withSandbox(({ project }) => {
+    const frozen = freezeRecipe({
+      projectDir: project,
+      name: "promo",
+      workflow: "product-launch-video",
+    });
+    assert.equal(frozen.workflow, "product-launch-video");
+    assert.equal(frozen.workflowOverridden, false);
+    assert.throws(() => freezeRecipe({ projectDir: project, name: "other" }), /no workflow found/);
+  });
+});
+
+test("freeze finds a legacy bare style_preset record; the scoped key wins over it", () => {
+  withSandbox(({ project }) => {
+    writeFileSync(join(project, "BRIEF.md"), BRIEF);
+    // A record made before the store required workflow scoping.
+    mkdirSync(join(project, ".media"), { recursive: true });
+    writeFileSync(
+      join(project, ".media/preferences.json"),
+      JSON.stringify({
+        version: 1,
+        preferences: {
+          style_preset: {
+            value: "source-paper-flowchart",
+            confirmed_in: ["my-launch"],
+            updated_at: "2026-07-15T00:00:00.000Z",
+          },
+        },
+        sightings: {},
+      }),
+    );
+    freezeRecipe({ projectDir: project, name: "promo" });
+    const legacy = JSON.parse(
+      readFileSync(join(project, ".media/recipes/promo/recipe.json"), "utf8"),
+    );
+    assert.equal(legacy.style_preset, "source-paper-flowchart");
+
+    recordPreference({
+      projectDir: project,
+      key: "style_preset",
+      value: "pin-and-paper",
+      workflow: "product-launch-video",
+    });
+    freezeRecipe({ projectDir: project, name: "promo" });
+    const scoped = JSON.parse(
+      readFileSync(join(project, ".media/recipes/promo/recipe.json"), "utf8"),
+    );
+    assert.equal(scoped.style_preset, "pin-and-paper");
+  });
+});
+
 test("re-freezing bumps the version and archives the old folder", () => {
   withSandbox(({ project }) => {
     freezeRecipe({ projectDir: project, name: "promo", workflow: "product-launch-video" });

skills/media-use/scripts/recipe.mjs

@@ -2,12 +2,14 @@
 /**
  * Recipes CLI — the heavyweight tier of HyperFrames user memory.
  *
- *   node recipe.mjs freeze --hyperframes . --name <n> --workflow <w> [--blocks a,b,c]
+ *   node recipe.mjs freeze --hyperframes . --name <n> [--workflow <w>] [--blocks a,b,c]
  *     Freeze the current approved run as a named recipe: frame.md + the
  *     storyboard skeleton (structure kept, content blanked) + the brief
  *     skeleton (when BRIEF.md exists) + the confirmed brief values.
- *     Re-freezing the same name bumps the version and archives the old
- *     folder as <name>@v<N>. Promotes to ~/.media/recipes/ immediately.
+ *     The workflow is read from BRIEF.md; --workflow only covers projects
+ *     briefed before BRIEF.md existed. Re-freezing the same name bumps the
+ *     version and archives the old folder as <name>@v<N>. Promotes to
+ *     ~/.media/recipes/ immediately.
  *
  *   node recipe.mjs list --hyperframes . [--workflow <w>] [--json]
  *     Two-tier merged listing (project wins), newest approval first.
@@ -57,7 +59,11 @@ try {
     });
     if (args.json) console.log(JSON.stringify({ ok: true, ...frozen }));
     else {
-      console.log(`froze recipe ${frozen.slug} (v${frozen.version}) → ${frozen.dir}`);
+      console.log(
+        `froze recipe ${frozen.slug} (v${frozen.version}, ${frozen.workflow}) → ${frozen.dir}`,
+      );
+      if (frozen.workflowOverridden)
+        console.log(`  (BRIEF.md says "${frozen.workflow}" — the --workflow flag was ignored)`);
       if (!frozen.briefSkeleton)
         console.log("  (no BRIEF.md in the project — brief skeleton skipped)");
     }