Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

fix(hypit): route completed variants into revision

rpone3cb50cc2a611
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.md
index 67b051e2..d3fe64b6 100644
--- a/.agents/skills/hypit/SKILL.md
+++ b/.agents/skills/hypit/SKILL.md
@@ -99,7 +99,7 @@ invalid. Never commit `.env` or copy its secret values into route state, Source,
hard-code video types or skip the brief-sufficiency gate.
- A completed project followed by a natural-language change → read `references/revision/route.md`
and use the independent `revision_state` route. The completed project may come from reconstruction,
- original authoring or an earlier revision, or the author may supply an existing completed project
+ original authoring, a completed variant or an earlier revision, or the author may supply an existing completed project
directory directly; it does not need to have been created in the current session. Restore the
element's role in the frozen intent, edit only Source/Recipe/Run, invalidate the affected graph
closure, and rerun deterministic gates. Revision never invokes VLM/observer visual inspection;
diff --git a/.agents/skills/hypit/references/recovery.md b/.agents/skills/hypit/references/recovery.md
index 16c5fbf3..0ed47215 100644
--- a/.agents/skills/hypit/references/recovery.md
+++ b/.agents/skills/hypit/references/recovery.md
@@ -45,6 +45,11 @@ first unmet `next_action`. `variant_init` reuses matching initialized copies and
destinations. A component/package digest change, missing inspection evidence or file outside
`allowed_changes` is a conflict, not permission to overwrite it.
+That rule applies while the child is still in its initial `variant` route. Once a completed child has
+started a user-requested Revision with `parent_route: variant`, its original `allowed_changes` is
+historical evidence only. Reconcile the Revision independently; do not rerun `variant_check` or report
+the Revision's authorized Source edits as variant batch scope conflicts.
+
For a completed project with a new natural-language change, use the current
`.hypit/revision-state.json` view and the execution directory named by its `revision_id` under
`.hypit/revisions/`. The immutable request is
diff --git a/.agents/skills/hypit/references/revision/route.md b/.agents/skills/hypit/references/revision/route.md
index 905c5afa..f7e500a4 100644
--- a/.agents/skills/hypit/references/revision/route.md
+++ b/.agents/skills/hypit/references/revision/route.md
@@ -1,7 +1,7 @@
# Post-completion natural-language revision route
Use this route whenever a natural-language change targets a completed Hypit project. The project may
-have just finished reconstruction, original authoring or an earlier revision, or the author may hand
+have just finished reconstruction, original authoring, variant expansion or an earlier revision, or the author may hand
over an already completed project directory directly. Revision does not require the current agent to
have created the project and does not require a parent creation route to exist.
@@ -30,6 +30,14 @@ hypit-reference-video-tools revision_state --action start \
--request 'raise the captions slightly'
```
+From one completed variant project, target that child directory rather than its base or batch root:
+
+```bash
+hypit-reference-video-tools revision_state --action start \
+ --project-root <batch>/023-example --run build.svrun --parent-route variant \
+ --request 'make the presenter framing tighter'
+```
+
From a directly supplied completed project with no parent route state:
```bash
@@ -69,7 +77,10 @@ and give the author the exact URL with the updated result.
1. Read the current `main.svml`, `recipes.svs`, `build.svrun`, runtime profile, brief and the target
package README/vocabulary. Recover the target element's role in the author's intent. For a
directly supplied project, use its authored Source, project documentation and current graph as the
- frozen intent evidence; do not force it through reconstruction or original authoring first.
+ frozen intent evidence; do not force it through reconstruction or original authoring first. For a
+ completed variant, read the parent variant route's `variant_brief`, `format_plan`, `component_plan`
+ and immutable final-check evidence. Its `allowed_changes` explains how the batch agent originally
+ produced that variant, but it is not an authorization boundary for the user's later Revision.
2. Classify the request's impact: geometry/style, Script/semantic timing, graph structure, or paid
generation. Record the affected Source files and the smallest invalidated graph closure.
3. Map natural language to the authoritative field before editing. A request such as “move the
@@ -77,8 +88,11 @@ and give the author the exact URL with the updated result.
Cue/SemanticTake/timing change; a new
component is a vocabulary-gap and package change. A Hook or opening change also requires checking
that later beats still fulfil its promise.
-4. Edit only Source, Recipe or Run. Re-run package/Cue gates, `hypit check`, `preview_check`, and the
- route-specific final check. Do not render, compare, review or inspect any frame during revision;
+4. Edit only Source, Recipe or Run. Re-run package/Cue gates, `hypit check` and `preview_check`, then
+ checkpoint their immutable evidence as the Revision final gate. When the parent is `variant`, do
+ **not** run `variant_check`: that command belongs only to initial batch production and would
+ reapply the old `allowed_changes` to a new user-authorized request. Do not render, compare, review
+ or inspect any frame during revision;
existing unchanged artifacts may be reused by digest. Once the gates pass, follow
`../studio-confirmation.md`'s conditional Studio handoff.
5. Check the final gate. Confirm cost again only when an image/video/voice generation input changed;
diff --git a/.agents/skills/hypit/references/variant-expansion/route.md b/.agents/skills/hypit/references/variant-expansion/route.md
index 8fb462b1..1c2104bd 100644
--- a/.agents/skills/hypit/references/variant-expansion/route.md
+++ b/.agents/skills/hypit/references/variant-expansion/route.md
@@ -63,6 +63,12 @@ reference reconstruction and apply that product/person/brand adaptation inside r
Variant expansion starts from that adapted, checked base. Revision is used only for a later natural-
language change to an already completed project.
+After an individual variant reaches `variant-complete`, a later natural-language change to that child
+project leaves this route and starts `../revision/route.md` with `--parent-route variant`. The original
+`allowed_changes` remains batch-production history; it does not constrain that Revision. Do not run
+`variant_check` after Revision has started. Later batch reconciliation validates the immutable check
+that completed the original variant and does not reinterpret Revision edits as batch scope escape.
+
## 2. Inspect examples and freeze format decisions
**Read now:** `../brief-intake.md`, then inspect complete projects under the checkout's `examples/`
diff --git a/packages/reference-video-tools/README.md b/packages/reference-video-tools/README.md
index aa1f45e1..8340ee64 100644
--- a/packages/reference-video-tools/README.md
+++ b/packages/reference-video-tools/README.md
@@ -20,7 +20,9 @@ For a completed project change, `revision_state --action start|read|checkpoint|r
small atomic current snapshot plus revision-scoped history. Revision edits Source/Recipe/Run and reruns
deterministic gates; it does not invoke a VLM/observer or perform visual review. The project may be
handed in as an already completed directory: after its baseline gates pass, Revision can start
-without a parent reconstruction or description route state.
+without a parent reconstruction or description route state. A completed child from variant expansion
+starts Revision with `--parent-route variant`; its original batch `allowed_changes` and `variant_check`
+apply only to initial production, not to the later user-authorized edit.
For a validated source project that needs independent derivatives, `variant_state` stores the atomic
batch snapshot and base-project locator, `variant_init` copies the authored project without generated
diff --git a/packages/reference-video-tools/src/cli.ts b/packages/reference-video-tools/src/cli.ts
index 7f2577ef..4b0a5bdd 100644
--- a/packages/reference-video-tools/src/cli.ts
+++ b/packages/reference-video-tools/src/cli.ts
@@ -32,7 +32,7 @@ function usage(): string {
" hypit-reference-video-tools variant_init --project-root <base> --output-root <batch> --slate <slate.json>",
" hypit-reference-video-tools variant_check --run <variant>/build.svrun [--runtime <hypit.runtime.json>]",
" route_state start: --route reconstruction|description|variant|variant-package [--run <run>] [--reference-id <id>]",
- " revision_state start: [--run <run>] [--parent-route reconstruction|description] [--request <text>]",
+ " revision_state start: [--run <run>] [--parent-route reconstruction|description|variant] [--request <text>]",
" checkpoint: --route <route> (--state <stage> | --step <n>) [--status in_progress|complete|blocked] [--next-action <text>] [--artifacts <json>]",
" read/reconcile: --project-root <dir>",
" hypit-reference-video-tools prepare_reference --video-path <path or link> [--observer gemini|agent] [--redo media|transcript|people|voices|systems|places|all]",
@@ -361,7 +361,7 @@ async function main(): Promise<void> {
result = await tools.revision_state(supplied as RevisionStateCommandInput);
} else if (action === "start") {
const parentRoute = one(flags, "parent-route");
- if (parentRoute !== undefined && parentRoute !== "reconstruction" && parentRoute !== "description") throw new Error("--parent-route must be reconstruction or description");
+ if (parentRoute !== undefined && parentRoute !== "reconstruction" && parentRoute !== "description" && parentRoute !== "variant") throw new Error("--parent-route must be reconstruction, description or variant");
result = await tools.revision_state({ action, project_root: projectRoot,
...(one(flags, "run") === undefined ? {} : { run: one(flags, "run") }),
...(parentRoute === undefined ? {} : { parent_route: parentRoute }),
@@ -376,6 +376,8 @@ async function main(): Promise<void> {
const step: number | string = Number.isSafeInteger(numericStep) && numericStep >= 1 ? numericStep : stepRaw;
const status = one(flags, "status");
if (status !== undefined && status !== "in_progress" && status !== "complete" && status !== "blocked") throw new Error("--status must be in_progress, complete or blocked");
+ const parentRoute = one(flags, "parent-route");
+ if (parentRoute !== undefined && parentRoute !== "reconstruction" && parentRoute !== "description" && parentRoute !== "variant") throw new Error("--parent-route must be reconstruction, description or variant");
let artifacts: Readonly<Record<string, string>> | undefined;
const artifactRaw = one(flags, "artifacts");
if (artifactRaw !== undefined) {
@@ -384,7 +386,7 @@ async function main(): Promise<void> {
result = await tools.revision_state({ action, project_root: projectRoot, step,
...(status === undefined ? {} : { status }),
...(one(flags, "run") === undefined ? {} : { run: one(flags, "run") }),
- ...(one(flags, "parent-route") === undefined ? {} : { parent_route: one(flags, "parent-route") as "reconstruction" | "description" }),
+ ...(parentRoute === undefined ? {} : { parent_route: parentRoute }),
...(one(flags, "parent-state-digest") === undefined ? {} : { parent_state_digest: one(flags, "parent-state-digest") }),
...(one(flags, "request") === undefined ? {} : { request: one(flags, "request") }),
...(one(flags, "next-action") === undefined ? {} : { next_action: one(flags, "next-action") }),
@@ -413,7 +415,7 @@ async function main(): Promise<void> {
const count = countRaw === undefined ? undefined : Number(countRaw);
if (count !== undefined && (!Number.isSafeInteger(count) || count < 1)) throw new Error("--count must be a positive integer");
const parentRoute = one(flags, "parent-route");
- if (parentRoute !== undefined && parentRoute !== "reconstruction" && parentRoute !== "description") throw new Error("--parent-route must be reconstruction or description");
+ if (parentRoute !== undefined && parentRoute !== "reconstruction" && parentRoute !== "description" && parentRoute !== "variant") throw new Error("--parent-route must be reconstruction, description or variant");
result = await tools.variant_state({
action, project_root: projectRoot, output_root: required(flags, "output-root"),
...(one(flags, "run") === undefined ? {} : { run: one(flags, "run") }),
diff --git a/packages/reference-video-tools/src/index.ts b/packages/reference-video-tools/src/index.ts
index 90714c0e..9a2851da 100644
--- a/packages/reference-video-tools/src/index.ts
+++ b/packages/reference-video-tools/src/index.ts
@@ -35,7 +35,7 @@ export {
REVISION_STATE_VERSION,
REVISION_STEPS,
} from "./revision-state.js";
-export type { RevisionCheckpointInput, RevisionState, RevisionStateInput, RevisionStatus, RevisionStep } from "./revision-state.js";
+export type { RevisionCheckpointInput, RevisionParentRoute, RevisionState, RevisionStateInput, RevisionStatus, RevisionStep } from "./revision-state.js";
export {
checkpointVariantExpansion,
discoverVariantExpansions,
diff --git a/packages/reference-video-tools/src/revision-state.ts b/packages/reference-video-tools/src/revision-state.ts
index 0292ea35..dee87678 100644
--- a/packages/reference-video-tools/src/revision-state.ts
+++ b/packages/reference-video-tools/src/revision-state.ts
@@ -6,6 +6,7 @@ import { atomicJson, digestPath, executionId, persistExecutionState } from "./st
/** A durable, small snapshot for a post-completion natural-language revision. */
export type RevisionStatus = "active" | "complete" | "blocked";
+export type RevisionParentRoute = "reconstruction" | "description" | "variant";
export type RevisionStep =
| "request-captured"
| "impact-assessed"
@@ -34,7 +35,7 @@ export type RevisionState = {
readonly revision_id: string;
readonly project_root: string;
readonly run?: string;
- readonly parent_route?: "reconstruction" | "description";
+ readonly parent_route?: RevisionParentRoute;
readonly parent_state_digest?: string;
readonly parent_state_path?: string;
readonly parent_revision_id?: string;
@@ -62,7 +63,7 @@ export type RevisionState = {
export type RevisionStateInput = {
readonly projectRoot: string;
readonly run?: string;
- readonly parentRoute?: "reconstruction" | "description";
+ readonly parentRoute?: RevisionParentRoute;
readonly parentStateDigest?: string;
readonly request?: string;
};
@@ -115,7 +116,7 @@ function assertState(value: unknown, path: string): asserts value is RevisionSta
if (state.version !== REVISION_STATE_VERSION) throw new Error(`revision state at ${path} has unsupported version`);
if (typeof state.revision_id !== "string" || state.revision_id.length === 0) throw new Error(`revision state at ${path} has no revision_id`);
if (typeof state.project_root !== "string" || state.project_root.length === 0) throw new Error(`revision state at ${path} has no project_root`);
- if (state.parent_route !== undefined && state.parent_route !== "reconstruction" && state.parent_route !== "description") throw new Error(`revision state at ${path} has invalid parent_route`);
+ if (state.parent_route !== undefined && state.parent_route !== "reconstruction" && state.parent_route !== "description" && state.parent_route !== "variant") throw new Error(`revision state at ${path} has invalid parent_route`);
if (state.parent_revision_id !== undefined && typeof state.parent_revision_id !== "string") throw new Error(`revision state at ${path} has invalid parent_revision_id`);
if (state.parent_revision_digest !== undefined && typeof state.parent_revision_digest !== "string") throw new Error(`revision state at ${path} has invalid parent_revision_digest`);
if (state.parent_revision_path !== undefined && typeof state.parent_revision_path !== "string") throw new Error(`revision state at ${path} has invalid parent_revision_path`);
@@ -189,7 +190,7 @@ export async function startRevisionState(input: RevisionStateInput): Promise<Rev
const parentStateDigest = input.parentStateDigest ?? (parentStatePath === undefined ? undefined : await digestPath(parentStatePath));
const parentRevisionPath = existing === undefined ? undefined : revisionExecutionStatePath(projectRoot, existing.revision_id);
const parentRevisionDigest = parentRevisionPath === undefined ? undefined : await digestPath(parentRevisionPath);
- const parentRoute = input.parentRoute ?? (parentState?.route === "reconstruction" || parentState?.route === "description" ? parentState.route : undefined);
+ const parentRoute = input.parentRoute ?? (parentState?.route === "reconstruction" || parentState?.route === "description" || parentState?.route === "variant" ? parentState.route : undefined);
const canonicalBrief = join(projectRoot, ".hypit", "brief.json");
const briefExists = await stat(canonicalBrief).then((value) => value.isFile(), () => false);
const intentBasis = parentRevisionPath ?? parentStatePath ?? (briefExists ? canonicalBrief : "supplied-project");
diff --git a/packages/reference-video-tools/src/tools.ts b/packages/reference-video-tools/src/tools.ts
index b5457210..ea0d4ddf 100644
--- a/packages/reference-video-tools/src/tools.ts
+++ b/packages/reference-video-tools/src/tools.ts
@@ -48,7 +48,7 @@ import {
revisionStatePath,
startRevisionState,
} from "./revision-state.js";
-import type { RevisionState, RevisionStep } from "./revision-state.js";
+import type { RevisionParentRoute, RevisionState, RevisionStep } from "./revision-state.js";
import { persistEvidence } from "./state-files.js";
import {
checkpointVariantExpansion,
@@ -231,13 +231,13 @@ export type RouteStateCommandInput =
| ({ readonly action: "checkpoint"; readonly project_root: string; readonly route: RouteKind; readonly step: number | RouteStep; readonly status?: "in_progress" | "complete" | "blocked"; readonly run?: string; readonly reference_id?: string; readonly next_action?: string; readonly artifacts?: Readonly<Record<string, string>>; readonly decision?: string; readonly command?: string; readonly error?: string });
export type RevisionStateCommandInput =
- | ({ readonly action: "start"; readonly project_root: string; readonly run?: string; readonly parent_route?: "reconstruction" | "description"; readonly parent_state_digest?: string; readonly request?: string })
+ | ({ readonly action: "start"; readonly project_root: string; readonly run?: string; readonly parent_route?: RevisionParentRoute; readonly parent_state_digest?: string; readonly request?: string })
| ({ readonly action: "read" | "reconcile"; readonly project_root: string })
- | ({ readonly action: "checkpoint"; readonly project_root: string; readonly step: number | RevisionStep; readonly status?: "in_progress" | "complete" | "blocked"; readonly run?: string; readonly parent_route?: "reconstruction" | "description"; readonly parent_state_digest?: string; readonly request?: string; readonly next_action?: string; readonly artifacts?: Readonly<Record<string, string>>; readonly decision?: string; readonly command?: string; readonly error?: string; readonly impact?: readonly string[]; readonly affected_source?: readonly string[] });
+ | ({ readonly action: "checkpoint"; readonly project_root: string; readonly step: number | RevisionStep; readonly status?: "in_progress" | "complete" | "blocked"; readonly run?: string; readonly parent_route?: RevisionParentRoute; readonly parent_state_digest?: string; readonly request?: string; readonly next_action?: string; readonly artifacts?: Readonly<Record<string, string>>; readonly decision?: string; readonly command?: string; readonly error?: string; readonly impact?: readonly string[]; readonly affected_source?: readonly string[] });
export type VariantStateCommandInput =
| ({ readonly action: "discover"; readonly project_root: string })
- | ({ readonly action: "start"; readonly project_root: string; readonly output_root: string; readonly run?: string; readonly request?: string; readonly count?: number; readonly delivery_mode?: "source" | "build"; readonly parent_route?: "reconstruction" | "description"; readonly parent_state_digest?: string; readonly revision_state_digest?: string })
+ | ({ readonly action: "start"; readonly project_root: string; readonly output_root: string; readonly run?: string; readonly request?: string; readonly count?: number; readonly delivery_mode?: "source" | "build"; readonly parent_route?: "reconstruction" | "description" | "variant"; readonly parent_state_digest?: string; readonly revision_state_digest?: string })
| ({ readonly action: "read" | "reconcile"; readonly project_root: string; readonly output_root?: string; readonly batch_id?: string })
| ({ readonly action: "checkpoint"; readonly project_root: string; readonly output_root?: string; readonly batch_id?: string; readonly step: number | VariantExpansionStep; readonly status?: "in_progress" | "complete" | "blocked"; readonly next_action?: string; readonly artifacts?: Readonly<Record<string, string>>; readonly workload_disclosure?: VariantWorkloadDisclosure; readonly packages?: readonly VariantExpansionPackage[]; readonly variants?: readonly VariantExpansionVariant[]; readonly decision?: string; readonly conflict?: string; readonly resolve_conflict?: string; readonly command?: string; readonly error?: string });
@@ -2651,6 +2651,10 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
const projectRoot = dirname(runPath);
const route = await readRouteState(projectRoot);
if (route?.route !== "variant") throw new Error(`${projectRoot} has no active variant route`);
+ const revision = await readRevisionState(projectRoot);
+ if (revision?.parent_route === "variant") {
+ throw new Error(`${projectRoot} has entered post-completion Revision; variant_check cannot reapply the original batch allowed_changes`);
+ }
const briefPath = join(projectRoot, ".hypit", "variant-brief.json");
const brief = JSON.parse(await readFile(briefPath, "utf8")) as {
id?: string;
diff --git a/packages/reference-video-tools/src/variant-state.ts b/packages/reference-video-tools/src/variant-state.ts
index e71d7878..a88461ed 100644
--- a/packages/reference-video-tools/src/variant-state.ts
+++ b/packages/reference-video-tools/src/variant-state.ts
@@ -72,7 +72,7 @@ export type VariantExpansionState = {
readonly output_root: string;
readonly run?: string;
readonly baseline_digest: string;
- readonly parent_route?: "reconstruction" | "description";
+ readonly parent_route?: "reconstruction" | "description" | "variant";
readonly parent_state_digest?: string;
readonly parent_state_path?: string;
readonly revision_state_digest?: string;
@@ -115,7 +115,7 @@ export type StartVariantExpansionInput = {
readonly request?: string;
readonly count?: number;
readonly deliveryMode?: "source" | "build";
- readonly parentRoute?: "reconstruction" | "description";
+ readonly parentRoute?: "reconstruction" | "description" | "variant";
readonly parentStateDigest?: string;
readonly revisionStateDigest?: string;
};
@@ -326,7 +326,7 @@ async function startVariantExpansionUnlocked(input: StartVariantExpansionInput):
if (parentRoute === undefined && parentStateBytes !== undefined) {
try {
const parsed = JSON.parse(parentStateBytes.toString()) as { route?: unknown };
- if (parsed.route === "reconstruction" || parsed.route === "description") parentRoute = parsed.route;
+ if (parsed.route === "reconstruction" || parsed.route === "description" || parsed.route === "variant") parentRoute = parsed.route;
} catch { /* corrupt parent state is reported by reconcile rather than hidden here */ }
}
const now = new Date().toISOString();
@@ -472,18 +472,25 @@ async function reconcileVariantExpansionUnlocked(projectRoot: string, outputRoot
const variants: VariantExpansionVariant[] = [];
for (const variant of existing.variants) {
const route = await reconcileRouteState(variant.project_root);
- const diff = await inspectVariantDiff(variant.project_root);
- const outside = Array.isArray(diff.outside_allowed_changes) ? diff.outside_allowed_changes : [];
- if (outside.length > 0) addConflict(`[reconcile] variant ${variant.id} changed outside allowed_changes: ${outside.join(", ")}`);
- if (diff.passed !== true && outside.length === 0) {
- const errors = Array.isArray(diff.errors) ? diff.errors.map(String).join(", ") : "variant baseline evidence failed";
- addConflict(`[reconcile] variant ${variant.id} scope evidence is invalid: ${errors}`);
+ const revision = await readRevisionState(variant.project_root);
+ const revisedAfterVariant = route?.route === "variant" && revision?.parent_route === "variant"
+ && revision.parent_state_path === routeExecutionStatePath(variant.project_root, route.route_id);
+ let outside: readonly unknown[] = [];
+ if (!revisedAfterVariant) {
+ const diff = await inspectVariantDiff(variant.project_root);
+ outside = Array.isArray(diff.outside_allowed_changes) ? diff.outside_allowed_changes : [];
+ if (outside.length > 0) addConflict(`[reconcile] variant ${variant.id} changed outside allowed_changes: ${outside.join(", ")}`);
+ if (diff.passed !== true && outside.length === 0) {
+ const errors = Array.isArray(diff.errors) ? diff.errors.map(String).join(", ") : "variant baseline evidence failed";
+ addConflict(`[reconcile] variant ${variant.id} scope evidence is invalid: ${errors}`);
+ }
}
const check = await validJson(route?.artifacts.variant_check ?? join(variant.project_root, ".hypit", "variant-check.json"), (value) => (value as { passed?: unknown })?.passed === true);
const { error: _oldError, ...variantWithoutError } = variant;
variants.push({
...variantWithoutError,
- status: outside.length > 0 ? "scope-expansion-required"
+ status: revisedAfterVariant && route?.status === "complete" && check ? "complete"
+ : outside.length > 0 ? "scope-expansion-required"
: route?.status === "complete" && check ? "complete"
: route?.status === "blocked" ? "failed" : route === undefined ? "failed" : variant.status === "ready" ? "ready" : "dispatched",
...(route === undefined ? { error: "route-state-missing" } : {}),