feat(build): allow draft PR body refs-only lint path (#14702) (#14703)

Author: neo-gpt

.agents/skills/pull-request/references/pull-request-workflow.md

@@ -281,6 +281,9 @@ Before PR prose, read [`reference-hygiene.md`](../../../../learn/agentos/process
   `Resolves #N`. `Closes` and `Fixes` are forbidden; comma-separated
   `Resolves #X, #Y` is forbidden. Multiple delivered tickets get one standalone
   line each.
+- Draft-only exception: `Refs #N` / `Related: #N` may replace `Resolves #N`
+  only while the PR is draft. Before `ready_for_review`, add the honest delivered
+  leaf close target or split/file the narrow ticket; that event reruns lint.
 - For referenced tickets that must remain open, branch history must also avoid
   stale magic-close keywords. Before handoff, run:
 

.github/workflows/agent-pr-body-lint.yml

@@ -1,7 +1,7 @@
 name: Agent PR Body Lint
 on:
   pull_request:
-    types: [opened, edited, synchronize]
+    types: [opened, edited, synchronize, ready_for_review]
 
 
 jobs:
@@ -15,6 +15,7 @@ jobs:
             const pr     = context.payload.pull_request;
             const author = pr.user.login;
             const body   = pr.body || "";
+            const isDraft = Boolean(pr.draft);
 
             // Only enforce for known AI agent accounts or PRs labeled with 'ai'
             const agentAuthors  = ['neo-opus-ada', 'neo-opus-grace', 'neo-opus-vega', 'neo-gemini-pro', 'neo-gpt'];
@@ -76,10 +77,12 @@ jobs:
             //     superseded / dropped) — that outcome needs NO PR, so a PR must never carry it.
             //   - `Fixes #N`  is FORBIDDEN: ambiguous; use `Resolves` (bug fixes included).
             //   - `Refs #N` / `Related: #N` are allowed as ADDITIONAL references (e.g. a parent
-            //     epic), and multiple `Resolves` lines are fine — but they never substitute for
-            //     the mandatory `Resolves`.
-            const hasResolves    = /\bResolves:?\s+#\d+/i.test(body);
-            const forbiddenClose = body.match(/\b(Closes|Fixes):?\s+#\d+/i);
+            //     epic). Draft PRs may temporarily use `Refs #N` / `Related: #N`
+            //     without `Resolves #N`, but `ready_for_review` reruns this workflow and
+            //     restores the mandatory close-target gate before handoff.
+            const hasResolves            = /\bResolves:?\s+#\d+/i.test(body);
+            const hasNonClosingReference = /\b(Refs|Related):?\s+#\d+/i.test(body);
+            const forbiddenClose         = body.match(/\b(Closes|Fixes):?\s+#\d+/i);
 
             if (forbiddenClose) {
               missingVisible.push(
@@ -88,8 +91,10 @@ jobs:
               );
             }
 
-            if (!hasResolves) {
-              missingVisible.push("`Resolves #N` (mandatory closing keyword — `Refs`/`Related` alone is NOT sufficient)");
+            if (!hasResolves && !(isDraft && hasNonClosingReference)) {
+              missingVisible.push(isDraft
+                ? "`Refs #N` or `Related: #N` (draft-only non-closing reference required when `Resolves #N` is absent)"
+                : "`Resolves #N` (mandatory closing keyword — `Refs`/`Related` alone is NOT sufficient)");
             }
 
             if (missingVisible.length === 0 && missingInvisible.length === 0) {

buildScripts/util/agent-preflight.mjs

@@ -24,8 +24,9 @@ export const INVISIBLE_PR_BODY_ANCHORS = [
 ];
 
 const
-    RESOLVES_PATTERN        = /\bResolves:?\s+#\d+/i,
-    FORBIDDEN_CLOSE_PATTERN = /\b(Closes|Fixes):?\s+#\d+/i;
+    RESOLVES_PATTERN              = /\bResolves:?\s+#\d+/i,
+    NON_CLOSING_REFERENCE_PATTERN = /\b(Refs|Related):?\s+#\d+/i,
+    FORBIDDEN_CLOSE_PATTERN       = /\b(Closes|Fixes):?\s+#\d+/i;
 
 /**
  * @summary Builds the Commander program for the agent preflight helper.
@@ -37,6 +38,7 @@ export function createProgram() {
         .description('Runs the agent commit/PR preflight gates in one pass; default mode may repair block alignment.')
         .usage('[options] [files...]')
         .option('--pr-body <file>', 'Run local PR-body template lint against the given markdown file.')
+        .option('--pr-draft', 'Validate --pr-body as a draft PR: Refs/Related may temporarily stand in for Resolves.')
         .option('--no-fix', 'Check-only mode: skip the check-block-alignment --fix repair pass.')
         .argument('[files...]', 'Optional file paths. When omitted, staged ACMR files are read from git.')
 }
@@ -56,10 +58,11 @@ export function parseArgs(argv) {
     const options = program.opts();
 
     return {
-        files : program.args,
-        fix   : options.fix,
-        help  : false,
-        prBody: options.prBody || null
+        files  : program.args,
+        fix    : options.fix,
+        help   : false,
+        prBody : options.prBody || null,
+        prDraft: options.prDraft || false
     }
 }
 
@@ -96,20 +99,26 @@ export function filterMjsFiles(files) {
 /**
  * @summary Mirrors the Agent PR Body Lint workflow's local body-shape checks.
  * @param {String} body
+ * @param {Object} [options]
+ * @param {Boolean} [options.draft=false]
  * @returns {Object}
  */
-export function validatePrBody(body) {
+export function validatePrBody(body, {draft = false} = {}) {
     const
-        missingVisible   = VISIBLE_PR_BODY_ANCHORS.filter(anchor => !body.includes(anchor)),
-        missingInvisible = INVISIBLE_PR_BODY_ANCHORS.filter(anchor => !body.includes(anchor)),
-        forbiddenClose   = body.match(FORBIDDEN_CLOSE_PATTERN);
+        missingVisible        = VISIBLE_PR_BODY_ANCHORS.filter(anchor => !body.includes(anchor)),
+        missingInvisible      = INVISIBLE_PR_BODY_ANCHORS.filter(anchor => !body.includes(anchor)),
+        forbiddenClose        = body.match(FORBIDDEN_CLOSE_PATTERN),
+        hasResolves           = RESOLVES_PATTERN.test(body),
+        hasNonClosingReference = NON_CLOSING_REFERENCE_PATTERN.test(body);
 
     if (forbiddenClose) {
         missingVisible.push(`\`${forbiddenClose[1]} #N\` is forbidden; use \`Resolves #N\``)
     }
 
-    if (!RESOLVES_PATTERN.test(body)) {
-        missingVisible.push('`Resolves #N` is required')
+    if (!hasResolves && !(draft && hasNonClosingReference)) {
+        missingVisible.push(draft
+            ? 'Draft PR bodies without `Resolves #N` require `Refs #N` or `Related: #N`'
+            : '`Resolves #N` is required')
     }
 
     return {
@@ -282,7 +291,7 @@ function runNodeGate({args, cwd, execFileSyncImpl, name}) {
     }
 }
 
-function runPrBodyGate({cwd, existsSyncImpl, prBody, readFileSyncImpl}) {
+function runPrBodyGate({cwd, existsSyncImpl, prBody, prDraft, readFileSyncImpl}) {
     const filePath = path.resolve(cwd, prBody);
 
     if (!existsSyncImpl(filePath)) {
@@ -293,7 +302,7 @@ function runPrBodyGate({cwd, existsSyncImpl, prBody, readFileSyncImpl}) {
         }
     }
 
-    return validatePrBody(readFileSyncImpl(filePath, 'utf8'))
+    return validatePrBody(readFileSyncImpl(filePath, 'utf8'), {draft: prDraft})
 }
 
 /**
@@ -387,6 +396,7 @@ export function runAgentPreflight({
             cwd,
             existsSyncImpl,
             prBody: options.prBody,
+            prDraft: options.prDraft,
             readFileSyncImpl
         });
 

test/playwright/unit/ai/buildScripts/util/agent-preflight.spec.mjs

@@ -29,6 +29,23 @@ const validBody = [
     '- None.'
 ].join('\n');
 
+const draftBody = [
+    'Refs #12345',
+    '',
+    'Authored by Euclid (GPT-5, Codex Desktop). Session test.',
+    '',
+    'Evidence: L2 local unit coverage. Draft-only helper; no close target yet.',
+    '',
+    '## Deltas from ticket',
+    '- Draft helper extracted before the leaf close target is complete.',
+    '',
+    '## Test Evidence',
+    '- npm run test-unit -- test/playwright/unit/ai/buildScripts/util/agent-preflight.spec.mjs',
+    '',
+    '## Post-Merge Validation',
+    '- None while draft.'
+].join('\n');
+
 test.describe('agent-preflight utility', () => {
     test('builds the Commander program with the expected option surface', () => {
         const program = createProgram();
@@ -38,16 +55,18 @@ test.describe('agent-preflight utility', () => {
         expect(help).toContain('default mode may repair');
         expect(help).toContain('block alignment');
         expect(help).toContain('--pr-body <file>');
+        expect(help).toContain('--pr-draft');
         expect(help).toContain('--no-fix');
         expect(help).toContain('Check-only mode')
     });
 
     test('parses files, optional PR body, and fix mode through Commander', () => {
-        expect(parseArgs(['--pr-body', 'body.md', '--no-fix', 'src/a.mjs'])).toEqual({
-            files : ['src/a.mjs'],
-            fix   : false,
-            help  : false,
-            prBody: 'body.md'
+        expect(parseArgs(['--pr-body', 'body.md', '--pr-draft', '--no-fix', 'src/a.mjs'])).toEqual({
+            files  : ['src/a.mjs'],
+            fix    : false,
+            help   : false,
+            prBody : 'body.md',
+            prDraft: true
         });
     });
 
@@ -64,6 +83,28 @@ test.describe('agent-preflight utility', () => {
         expect(validatePrBody(validBody).valid).toBe(true)
     });
 
+    test('accepts a draft PR body with a non-closing reference instead of Resolves', () => {
+        const result = validatePrBody(draftBody, {draft: true});
+
+        expect(result.valid).toBe(true);
+        expect(result.missingVisible).toEqual([]);
+        expect(result.missingInvisible).toEqual([])
+    });
+
+    test('keeps Refs-only bodies invalid for ready PR validation', () => {
+        const result = validatePrBody(draftBody);
+
+        expect(result.valid).toBe(false);
+        expect(result.missingVisible).toContain('`Resolves #N` is required')
+    });
+
+    test('requires at least a non-closing issue reference for draft bodies without Resolves', () => {
+        const result = validatePrBody(draftBody.replace('Refs #12345', 'Draft-only note.'), {draft: true});
+
+        expect(result.valid).toBe(false);
+        expect(result.missingVisible).toContain('Draft PR bodies without `Resolves #N` require `Refs #N` or `Related: #N`')
+    });
+
     test('reports visible misses and forbidden close keywords without naming structural anchors', () => {
         const result = validatePrBody([
             'Closes #12345',
@@ -178,6 +219,26 @@ test.describe('agent-preflight utility', () => {
         expect(stdout).toContain('agent-preflight: PR body contains the required template anchors.')
     });
 
+    test('runs the draft PR body gate when requested', () => {
+        let stdout = '';
+        let stderr = '';
+
+        const status = runAgentPreflight({
+            argv            : ['--pr-body', 'body.md', '--pr-draft'],
+            cwd             : '/repo',
+            execFileSyncImpl: cmd => cmd === 'git' ? '' : '',
+            existsSyncImpl  : () => true,
+            readFileSyncImpl: () => draftBody,
+            stderr          : {write: value => { stderr += value }},
+            stdout          : {write: value => { stdout += value }}
+        });
+
+        expect(status).toBe(0);
+        expect(stderr).toBe('');
+        expect(stdout).toContain('agent-preflight: 0 .mjs files in scope; skipped source gates.');
+        expect(stdout).toContain('agent-preflight: PR body contains the required template anchors.')
+    });
+
     test('returns failure when the local PR body is missing required anchors', () => {
         let stderr = '';