Merge pull request #2599 from heygen-com/via/composition-structure-mandate

feat(skills): add COMPOSITION_STRUCTURE to feedback repro packet + soft-warn lint

packages/cli/src/commands/coreSkillContent.test.ts

@@ -35,6 +35,20 @@ describe("hyperframes-core contract docs", () => {
     expect(renderReference).toContain("OUTCOME:");
     expect(renderReference).toContain("WORKAROUND:");
   });
+
+  it("mandates a composition-structure block for visual-defect feedback", () => {
+    const skill = read("skills", "hyperframes-cli", "SKILL.md");
+    const renderReference = read("skills", "hyperframes-cli", "references", "preview-render.md");
+
+    // Skill teaches the mandate at a high level.
+    expect(skill).toContain("COMPOSITION_STRUCTURE:");
+    // Reference carries the fillable block + agent-helper pointer.
+    expect(renderReference).toContain("COMPOSITION_STRUCTURE:");
+    expect(renderReference).toContain("elements: video=");
+    expect(renderReference).toContain("attributes:");
+    expect(renderReference).toContain("timeline:");
+    expect(renderReference).toContain("buildCompositionCensus");
+  });
 });
 
 describe("media-use TTS documentation", () => {

packages/cli/src/commands/feedback.ts

@@ -12,6 +12,7 @@ import { buildIssueUrl, HYPERFRAMES_REPO_URL } from "../utils/feedbackIssue.js";
 import { VERSION } from "../version.js";
 import { c } from "../ui/colors.js";
 import { parseFeedbackRating } from "../utils/feedbackRating.js";
+import { lintFeedbackComment, type FeedbackLintInput } from "../utils/feedbackLint.js";
 
 export const examples: Example[] = [
   ["Submit render feedback", 'hyperframes feedback --rating 8 --comment "fast but font missing"'],
@@ -78,6 +79,18 @@ async function publishRepro(dir: string): Promise<string | undefined> {
   }
 }
 
+/**
+ * Print soft-warn feedback-lint messages to stdout. Extracted so the
+ * command's `run` stays a flat control-flow driver — the warning loop is
+ * incidental to the command logic and its complexity would otherwise push
+ * `run` over the Fallow CRAP threshold.
+ */
+function printFeedbackLintWarnings(input: FeedbackLintInput): void {
+  for (const warning of lintFeedbackComment(input)) {
+    console.log(c.warn(`⚠ ${warning.message}`));
+  }
+}
+
 async function openAndPrintIssue(url: string): Promise<void> {
   if (process.stdout.isTTY) {
     try {
@@ -156,6 +169,11 @@ export default defineCommand({
     const comment = normalizeComment(args.comment);
     const doctorSummary = await getDoctorSummary();
 
+    // Soft-warn (never blocks) when the comment for a non-clean report is
+    // missing the mandated reproduction-packet markers. Prints before the
+    // submission ack so the reporter sees the nudge while their run is fresh.
+    printFeedbackLintWarnings({ rating, comment });
+
     // The standalone command runs separately from `render`, so it has no real
     // elapsed time to report. Omit it rather than recording a fake duration.
     trackRenderFeedback({ rating, comment, doctorSummary });