@officexapp/vidfarm-devcli 0.21.33 → 0.21.35

package/dist/src/devcli/{qa-regime.js → harness.js}

@@ -1,17 +1,31 @@
-// QA_REGIME.md — a per-style quality contract for a template family.
+// HARNESS.md — the reusable AI harness for one format or template.
 //
-// WHY IT EXISTS: `vidfarm qa`'s built-in rules are UNIVERSAL (no HTML slop, the
-// font regime, the thumbnail frame) — they are the same for every video anyone
-// makes, so they can live in code. A regime is the opposite: it is what makes
-// THIS director's THIS format good, and it changes per account, per offer, per
-// campaign. That can't be hard-coded, so it lives next to the work as Markdown
-// the director owns, edits, and versions.
+// A HARNESS is the written apparatus that lets an agent reproduce what makes a
+// format good, over and over, without the director in the room. It is the unit
+// the product is organised around: "create me a harness", "update the harness
+// for this format", and "give me the harness for this template_id" are all the
+// same noun, arrived at from different directions.
+//
+// TWO PROVENANCES, ONE ARTIFACT:
+//   • DERIVED  — `vidfarm harness derive <forkId|dir>` distils a decomposed
+//     template's DNA (viral / visual / structural / audio / build) into a
+//     HARNESS.md. This is what "the harness for this template_id" means.
+//   • AUTHORED — `vidfarm harness init <base>` copies a bundled starting point
+//     the director then edits into their own format contract.
+// Both produce the same file, and a derived one is still meant to be edited.
+//
+// WHY IT ISN'T CODE: `vidfarm qa`'s built-in rules are UNIVERSAL (no HTML slop,
+// the caption font regime, the thumbnail frame) — the same for every video
+// anyone makes, so they live in code. A harness is the opposite: it is what
+// makes THIS format good, and it changes per account, per offer, per campaign,
+// per source template. So it lives next to the work as Markdown the director
+// owns, edits, versions, and hands to the next agent.
 //
 // It matters most in SCRIPTING MODE. One video gets human eyes on every frame;
-// fifty variants generated in a loop do not. The regime is what a bulk run is
+// fifty variants generated in a loop do not. The harness is what a bulk run is
 // graded against — the thing that keeps variant #37 as good as variant #1.
 //
-// THE FORMAT is a plain Markdown doc with two machine-readable affordances:
+// THE FORMAT is a plain Markdown doc with three machine-readable affordances:
 //
 //   1. Optional YAML-ish front matter with a `checks:` block. These are the
 //      assertions the CLI can settle DETERMINISTICALLY from the composition DOM
@@ -21,27 +35,34 @@
 //      a question the CLI hands back for the agent (or the human) to answer.
 //      "Is the withheld answer one the viewer can't supply themselves?" is a
 //      judgment call; pretending a linter can settle it would be a lie.
+//   3. Any heading containing "DNA" is indexed as a DNA SECTION, so a harness
+//      speaks the same vocabulary the decompose pass writes into the template
+//      JSON (viral_dna, visual_dna, …) and an agent can ask for one strand by
+//      name instead of re-reading the whole doc.
 //
 // Everything else is prose the agent reads for context. That split is the whole
 // design: the CLI is honest about which half it can enforce, and it never
 // silently "passes" a video on the strength of the half it can't.
 //
-// COMPOSABLE BY CONSTRUCTION: regimes stack (`--regime a --regime b`), resolve
-// from a built-in name OR any path the user points at, and a directory's own
-// QA_REGIME.md is picked up automatically. Nothing here is a gate — same
-// feedback-not-a-gate contract as the rest of `vidfarm qa`.
+// COMPOSABLE BY CONSTRUCTION: harnesses stack (`--harness a --harness b`),
+// resolve from a built-in name OR any path the user points at, and a
+// directory's own HARNESS.md is picked up automatically. Nothing here is a gate
+// — same feedback-not-a-gate contract as the rest of `vidfarm qa`.
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-const BUILTIN_SUFFIX = ".QA_REGIME.md";
-// ── Locating the built-in regimes ────────────────────────────────────────────
-// They ship inside the skill pack (.agents/skills/vidfarm/regimes/) rather than
-// as TS string constants, so a director can read, diff, and copy them as normal
-// files — the file IS the documentation.
+const BUILTIN_SUFFIX = ".HARNESS.md";
+/** The canonical filename, plus the legacy names we still read (never write). */
+export const HARNESS_FILENAME = "HARNESS.md";
+const DISCOVERY_NAMES = ["HARNESS.md", "harness.md", "QA_REGIME.md", "qa_regime.md", "QA-REGIME.md"];
+// ── Locating the built-in harnesses ──────────────────────────────────────────
+// They ship inside the skill pack (.agents/skills/vidfarm/harnesses/) rather
+// than as TS string constants, so a director can read, diff, and copy them as
+// normal files — the file IS the documentation.
 function builtinDir() {
     let dir = path.dirname(fileURLToPath(import.meta.url));
     for (let i = 0; i < 6; i += 1) {
-        const candidate = path.join(dir, ".agents", "skills", "vidfarm", "regimes");
+        const candidate = path.join(dir, ".agents", "skills", "vidfarm", "harnesses");
         if (existsSync(candidate))
             return candidate;
         const parent = path.dirname(dir);
@@ -51,7 +72,7 @@ function builtinDir() {
     }
     return null;
 }
-export function listBuiltinRegimes() {
+export function listBuiltinHarnesses() {
     const dir = builtinDir();
     if (!dir)
         return [];
@@ -60,12 +81,12 @@ export function listBuiltinRegimes() {
         .sort()
         .map((file) => {
         const full = path.join(dir, file);
-        const parsed = parseRegime(readFileSync(full, "utf8"), full);
+        const parsed = parseHarness(readFileSync(full, "utf8"), full);
         return { name: file.slice(0, -BUILTIN_SUFFIX.length), path: full, video_type: parsed.video_type, summary: parsed.summary };
     });
 }
-/** Resolve `hooks` (built-in) or `./my/QA_REGIME.md` (a path) to a file. */
-export function resolveRegimePath(ref) {
+/** Resolve `hooks` (built-in) or `./my/HARNESS.md` (a path) to a file. */
+export function resolveHarnessPath(ref) {
     const direct = path.resolve(ref);
     if (existsSync(direct) && !direct.endsWith(path.sep))
         return direct;
@@ -75,18 +96,28 @@ export function resolveRegimePath(ref) {
         if (existsSync(candidate))
             return candidate;
     }
-    const names = listBuiltinRegimes().map((entry) => entry.name);
-    throw new Error(`No QA regime "${ref}". Pass a file path, or one of the built-ins: ${names.join(", ") || "(none bundled)"}. ` +
-        `Scaffold your own with \`vidfarm regime init <name> --out ./work/QA_REGIME.md\`.`);
+    const names = listBuiltinHarnesses().map((entry) => entry.name);
+    throw new Error(`No harness "${ref}". Pass a file path, or one of the built-ins: ${names.join(", ") || "(none bundled)"}. ` +
+        `Scaffold your own with \`vidfarm harness init <name> --out ./work/HARNESS.md\`, ` +
+        `or derive one from a decomposed template with \`vidfarm harness derive <forkId>\`.`);
 }
-/** A directory's own regime, if it has one. Case-tolerant on the filename. */
-export function discoverRegime(dir) {
-    for (const name of ["QA_REGIME.md", "qa_regime.md", "QA-REGIME.md"]) {
+/**
+ * A directory's own harness, if it has one. `HARNESS.md` is canonical; the
+ * legacy `QA_REGIME.md` names are still read so existing work directories keep
+ * working, but nothing writes them any more.
+ */
+export function discoverHarness(dir) {
+    for (const name of DISCOVERY_NAMES) {
         const candidate = path.join(dir, name);
         if (existsSync(candidate))
             return candidate;
     }
-    return null;
+    const nested = path.join(dir, ".harness", HARNESS_FILENAME);
+    return existsSync(nested) ? nested : null;
+}
+/** True for the legacy filenames, so callers can nudge without breaking. */
+export function isLegacyHarnessFilename(file) {
+    return /^qa[_-]regime\.md$/i.test(path.basename(file));
 }
 /**
  * A deliberately tiny front-matter reader: `key: value`, and one level of
@@ -149,9 +180,15 @@ function parseFrontMatter(raw) {
 const KNOWN_CHECKS = new Set([
     "duration_sec", "aspect", "first_frame_visual", "first_frame_text", "hook_words_max",
     "text_by_sec", "audio", "captions", "font_regime", "safe_zone", "forbid_text",
-    "require_text", "max_text_cards", "max_simultaneous_text", "scenes", "max_scene_sec"
+    "require_text", "max_text_cards", "max_simultaneous_text", "max_words_per_cue", "max_dead_air_sec",
+    "max_tail_sec", "scenes", "max_scene_sec"
 ]);
-export function parseRegime(raw, source) {
+/** "Visual DNA — the look" → `visual_dna`. Matches the decompose JSON keys. */
+function dnaKey(heading) {
+    const head = heading.split(/[—–:(]/)[0];
+    return head.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+}
+export function parseHarness(raw, source) {
     const { front, body } = parseFrontMatter(raw);
     const checks = {};
     const unknown = [];
@@ -165,13 +202,27 @@ export function parseRegime(raw, source) {
             unknown.push(bare);
     }
     const reviewItems = [];
+    const dna = [];
+    let openDna = null;
+    let openDnaLevel = 0;
     let section = "Checklist";
     for (const line of body.split(/\r?\n/)) {
-        const heading = line.match(/^#{1,6}\s+(.*)$/);
+        const heading = line.match(/^(#{1,6})\s+(.*)$/);
         if (heading) {
-            section = heading[1].replace(/[*_`]/g, "").trim();
+            section = heading[2].replace(/[*_`]/g, "").trim();
+            // A "…DNA" heading opens a strand; the next heading at the same level or
+            // shallower closes it, so nested sub-headings stay inside their strand.
+            if (openDna && heading[1].length <= openDnaLevel)
+                openDna = null;
+            if (/\bdna\b/i.test(section)) {
+                openDna = { key: dnaKey(section), heading: section, body: "" };
+                openDnaLevel = heading[1].length;
+                dna.push(openDna);
+            }
             continue;
         }
+        if (openDna)
+            openDna.body += `${line}\n`;
         const bold = line.match(/^\*\*(.+?)\*\*\s*$/);
         if (bold) {
             section = bold[1].trim();
@@ -181,14 +232,19 @@ export function parseRegime(raw, source) {
         if (box)
             reviewItems.push({ section, text: box[2].trim() });
     }
+    for (const strand of dna)
+        strand.body = strand.body.trim();
     const headline = body.split(/\r?\n/).find((line) => line.trim() && !line.startsWith("#") && !line.startsWith(">"));
-    const name = String(front.name ?? path.basename(source).replace(/\.md$/i, "").replace(/\.QA_REGIME$/i, ""));
+    const name = String(front.name ?? path.basename(source).replace(/\.md$/i, "").replace(/\.(HARNESS|QA_REGIME)$/i, ""));
     return {
         name,
         source,
         video_type: front.video_type ? String(front.video_type) : null,
         summary: headline ? headline.replace(/[*_`]/g, "").trim().slice(0, 160) : null,
+        derived_from: front.derived_from ? String(front.derived_from) : null,
+        source_template_id: front.source_template_id ? String(front.source_template_id) : null,
         checks,
+        dna,
         review_items: reviewItems,
         unknown_check_keys: unknown
     };
@@ -225,15 +281,15 @@ function isRequired(value) {
 function isForbidden(value) {
     return String(value ?? "").trim().toLowerCase() === "forbidden";
 }
-export function evaluateRegime(parsed, facts) {
+export function evaluateHarness(parsed, facts) {
     const checks = [];
     const findings = [];
-    const where = `QA_REGIME "${parsed.name}"`;
+    const where = `harness "${parsed.name}"`;
     const settle = (key, expected, actual, ok, fix) => {
         checks.push({ key, expected, actual, ok });
         if (!ok) {
             findings.push({
-                rule: `regime:${key}`,
+                rule: `harness:${key}`,
                 severity: "error",
                 message: `${parsed.name}: ${key} expects ${expected} — this composition is ${actual}.`,
                 where,
@@ -244,7 +300,7 @@ export function evaluateRegime(parsed, facts) {
     const c = parsed.checks;
     if (c.duration_sec !== undefined && facts.duration_sec !== null) {
         const spec = String(c.duration_sec);
-        settle("duration_sec", spec, `${facts.duration_sec.toFixed(1)}s`, rangeSatisfied(spec, facts.duration_sec), "Retime the timeline (`vidfarm retime` / `vidfarm ripple`) or set the composition duration to land inside the regime's window.");
+        settle("duration_sec", spec, `${facts.duration_sec.toFixed(1)}s`, rangeSatisfied(spec, facts.duration_sec), "Retime the timeline (`vidfarm retime` / `vidfarm ripple`) or set the composition duration to land inside the harness's window.");
     }
     if (c.aspect !== undefined && facts.canvas.aspect) {
         const allowed = String(c.aspect).split(/[|,]/).map((entry) => entry.trim());
@@ -259,7 +315,7 @@ export function evaluateRegime(parsed, facts) {
             settle("first_frame_text", "hook words up at t=0", has ? `"${facts.first_frame_text}"` : "no text at t=0", has, "Start the hook caption at 0 so the thumbnail states the promise before a word is spoken (muted autoplay is the default).");
         }
         else if (isForbidden(c.first_frame_text)) {
-            settle("first_frame_text", "no text at t=0", has ? `"${facts.first_frame_text}"` : "clean", !has, "Delay the first text layer past 0 — this regime wants the opening frame to carry the image alone.");
+            settle("first_frame_text", "no text at t=0", has ? `"${facts.first_frame_text}"` : "clean", !has, "Delay the first text layer past 0 — this harness wants the opening frame to carry the image alone.");
         }
     }
     if (c.hook_words_max !== undefined) {
@@ -282,7 +338,7 @@ export function evaluateRegime(parsed, facts) {
             settle("audio", "at least one audio layer", `${facts.audio_layers}`, facts.audio_layers > 0, "Add narration or a bed (`vidfarm tts` free local voice, or `vidfarm media search --type bgm`).");
         }
         else if (isForbidden(c.audio)) {
-            settle("audio", "no audio layers", `${facts.audio_layers}`, facts.audio_layers === 0, "Remove the audio layers — this regime is for silent/overlay output.");
+            settle("audio", "no audio layers", `${facts.audio_layers}`, facts.audio_layers === 0, "Remove the audio layers — this harness is for silent/overlay output.");
         }
     }
     if (isRequired(c.captions)) {
@@ -298,11 +354,11 @@ export function evaluateRegime(parsed, facts) {
     }
     for (const phrase of asList(c.forbid_text)) {
         const hit = phrase && new RegExp(phrase.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i").test(facts.all_text);
-        settle("forbid_text", `no "${phrase}" on screen`, hit ? `found "${phrase}"` : "absent", !hit, "Rewrite the line. The regime bans this phrasing for a reason recorded in the doc — read the section it sits under.");
+        settle("forbid_text", `no "${phrase}" on screen`, hit ? `found "${phrase}"` : "absent", !hit, "Rewrite the line. The harness bans this phrasing for a reason recorded in the doc — read the section it sits under.");
     }
     for (const phrase of asList(c.require_text)) {
         const hit = phrase && new RegExp(phrase.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i").test(facts.all_text);
-        settle("require_text", `"${phrase}" appears on screen`, hit ? "present" : "missing", Boolean(hit), "Add the required line as a timed caption — this is usually a compliance or positioning beat the regime treats as mandatory.");
+        settle("require_text", `"${phrase}" appears on screen`, hit ? "present" : "missing", Boolean(hit), "Add the required line as a timed caption — this is usually a compliance or positioning beat the harness treats as mandatory.");
     }
     if (c.max_text_cards !== undefined) {
         const max = Number(c.max_text_cards);
@@ -316,9 +372,27 @@ export function evaluateRegime(parsed, facts) {
             settle("max_simultaneous_text", `≤${max} text runs at once`, `${facts.max_simultaneous_text}`, facts.max_simultaneous_text <= max, "Stagger the overlapping text layers. Two things to read at once means neither gets read.");
         }
     }
+    if (c.max_words_per_cue !== undefined) {
+        const max = Number(c.max_words_per_cue);
+        if (Number.isFinite(max)) {
+            settle("max_words_per_cue", `≤${max} words in any one text run`, `${facts.max_words_in_run}`, facts.max_words_in_run <= max, "Page the long run into kinetic cues — `vidfarm captions generate <dir> --style word-pop` splits narration into ~3–5-word cues on real word timings. A paragraph on screen gets read by nobody.");
+        }
+    }
+    if (c.max_dead_air_sec !== undefined) {
+        const max = Number(c.max_dead_air_sec);
+        if (Number.isFinite(max)) {
+            settle("max_dead_air_sec", `≤${max}s with nothing to read`, `${facts.max_dead_air_sec}s`, facts.max_dead_air_sec <= max, "Run the deletion test on that stretch and cut it, then CLOSE the hole with `vidfarm ripple <dir> --at <sec> --delta -<sec>`. Dead screen time is a free exit.");
+        }
+    }
+    if (c.max_tail_sec !== undefined) {
+        const max = Number(c.max_tail_sec);
+        if (Number.isFinite(max)) {
+            settle("max_tail_sec", `≤${max}s after the last word`, `${facts.tail_silence_sec}s`, facts.tail_silence_sec <= max, "End on the bait. Trim the trailing clip and pull the composition duration in so the last frame is the one that loops best.");
+        }
+    }
     if (c.scenes !== undefined) {
         const spec = String(c.scenes);
-        settle("scenes", `${spec} visual clips`, `${facts.visual_clips.length}`, rangeSatisfied(spec, facts.visual_clips.length), "Split or merge scenes to hit the regime's pacing shape (`vidfarm split` / `vidfarm retime`).");
+        settle("scenes", `${spec} visual clips`, `${facts.visual_clips.length}`, rangeSatisfied(spec, facts.visual_clips.length), "Split or merge scenes to hit the harness's pacing shape (`vidfarm split` / `vidfarm retime`).");
     }
     if (c.max_scene_sec !== undefined) {
         const max = Number(c.max_scene_sec);
@@ -329,7 +403,7 @@ export function evaluateRegime(parsed, facts) {
     }
     for (const key of parsed.unknown_check_keys) {
         findings.push({
-            rule: "regime:unknown-check",
+            rule: "harness:unknown-check",
             severity: "warn",
             message: `${parsed.name}: unknown check "${key}" — ignored (the CLI can't settle it).`,
             where,
@@ -340,22 +414,23 @@ export function evaluateRegime(parsed, facts) {
         name: parsed.name,
         source: parsed.source,
         video_type: parsed.video_type,
+        dna: parsed.dna.map((strand) => strand.key),
         checks,
         review_items: parsed.review_items,
         findings
     };
 }
-export function loadAndEvaluateRegime(ref, facts) {
-    const file = resolveRegimePath(ref);
-    return evaluateRegime(parseRegime(readFileSync(file, "utf8"), file), facts);
+export function loadAndEvaluateHarness(ref, facts) {
+    const file = resolveHarnessPath(ref);
+    return evaluateHarness(parseHarness(readFileSync(file, "utf8"), file), facts);
 }
 /**
- * Fold regime results into a QaReport. Regime failures are the DIRECTOR's own
+ * Fold harness results into a QaReport. Harness failures are the DIRECTOR's own
  * rules, so they land in the same errors list as the built-ins — but the verdict
  * stays advisory: `vidfarm qa` still exits 0 unless the caller asked for
  * --strict, exactly as it does for slop.
  */
-export function mergeRegimeIntoReport(report, evaluations) {
+export function mergeHarnessIntoReport(report, evaluations) {
     const findings = evaluations.flatMap((evaluation) => evaluation.findings);
     const errors = [...report.errors, ...findings.filter((finding) => finding.severity === "error")];
     const warnings = [...report.warnings, ...findings.filter((finding) => finding.severity === "warn")];
@@ -365,17 +440,19 @@ export function mergeRegimeIntoReport(report, evaluations) {
         verdict: errors.length ? "slop" : warnings.length ? "warnings" : "clean",
         errors,
         warnings,
-        regimes: evaluations
+        harnesses: evaluations
     };
 }
-/** Human-readable regime block for the CLI (findings are printed by qa itself). */
-export function formatRegimeReport(evaluation, colors) {
+/** Human-readable harness block for the CLI (findings are printed by qa itself). */
+export function formatHarnessReport(evaluation, colors) {
     const { green, red, dim, reset } = colors;
     const lines = [];
     const failed = evaluation.checks.filter((check) => !check.ok).length;
-    lines.push(`${dim}regime${reset} ${evaluation.name}${evaluation.video_type ? ` ${dim}(${evaluation.video_type})${reset}` : ""} ` +
+    lines.push(`${dim}harness${reset} ${evaluation.name}${evaluation.video_type ? ` ${dim}(${evaluation.video_type})${reset}` : ""} ` +
         `${dim}— ${evaluation.checks.length - failed}/${evaluation.checks.length} machine checks passed, ` +
         `${evaluation.review_items.length} item(s) need your judgment${reset}`);
+    if (evaluation.dna.length)
+        lines.push(`  ${dim}DNA documented: ${evaluation.dna.join(", ")}${reset}`);
     for (const check of evaluation.checks) {
         const mark = check.ok ? `${green}✓${reset}` : `${red}✗${reset}`;
         lines.push(`  ${mark} ${check.key} ${dim}expects ${check.expected} — got ${check.actual}${reset}`);
@@ -393,4 +470,4 @@ export function formatRegimeReport(evaluation, colors) {
     }
     return lines.join("\n");
 }
-//# sourceMappingURL=qa-regime.js.map
+//# sourceMappingURL=harness.js.map