fix(ci): skill docs may name the project files a workflow writes (#4902)

* fix(ci): skill docs may name the project files a workflow writes

* style(ci): wrap the project-file citation test to the format width

Author: miguel-heygen

scripts/check-comment-citations.mjs

@@ -123,8 +123,12 @@ const ALLOW = new Set([
   ...REACT_DOM_EXPORTS,
 ]);
 
-// A URL, an absolute path, a `<sha>:<path>`, or build output: none of these resolve in the tree.
+// Files a skill workflow writes into the user's project at run time; skill docs name them bare.
+const PROJECT_FILES = new Set(["frame.md", "STORYBOARD.md", "SCRIPT.md", "_role.md"]);
+
+// A URL, an absolute path, a `<sha>:<path>`, build output or a project file: none resolve in the tree.
 function namesSomethingElse(cited) {
+  if (PROJECT_FILES.has(cited)) return true;
   if (cited.startsWith("/") || cited.startsWith("~")) return true;
   if (cited.includes(":")) return true;
   return cited.split("/")[0] === "dist";

scripts/check-comment-citations.test.mjs

@@ -67,6 +67,23 @@ test("a cited file that does not exist fails", (t) => {
   assert.equal(failures[0].where, "src/subject.ts:1");
 });
 
+test("a bare project file a skill workflow writes is not this repo's to resolve", (t) => {
+  const { failures } = checkSubject(t, {
+    "skills/demo/references/visual-design.md": ["Enrich `STORYBOARD.md` from `frame.md`.", ""].join(
+      "\n",
+    ),
+  });
+  assert.deepEqual(failures, []);
+});
+
+test("a repo path ending in a project file name is still resolved", (t) => {
+  const { failures } = checkSubject(t, {
+    "skills/demo/references/visual-design.md": ["See `skills/demo/frame.md`.", ""].join("\n"),
+  });
+  assert.equal(failures.length, 1);
+  assert.match(failures[0].why, /no such file/);
+});
+
 test("a line number past the end of a real file fails", (t) => {
   const { failures } = checkSubject(t, {
     "src/subject.ts": oneLiner("// Defined at `src/brand.ts:99`."),