chore: mechanize pr readiness authoring

Author: mk3008

.github/pull_request_template.md

@@ -11,29 +11,30 @@
 - [ ] No baseline exception requested.
 - [ ] Baseline exception requested and linked below.
 
-Tracking issue:
-Scoped checks run:
-Why full baseline is not required:
+<!-- Write values on the same line as each label, or generate this section via `pnpm pr:readiness:prepare ...`. -->
+Tracking issue: 
+Scoped checks run: 
+Why full baseline is not required: 
 
 ## CLI Surface Migration
 
 - [ ] No migration packet required for this CLI change.
 - [ ] CLI/user-facing surface change and migration packet completed.
 
-<!-- Fill the fields below as plain label lines. Do not add list markers like "-" before labels. -->
-No-migration rationale:
-Upgrade note:
-Deprecation/removal plan or issue:
-Docs/help/examples updated:
-Release/changeset wording:
+<!-- Fill the fields below on the same line as each label, or generate this section via `pnpm pr:readiness:prepare ...`. Do not add list markers like "-" before labels. -->
+No-migration rationale: 
+Upgrade note: 
+Deprecation/removal plan or issue: 
+Docs/help/examples updated: 
+Release/changeset wording: 
 
 ## Scaffold Contract Proof
 
 - [ ] No scaffold contract proof required for this PR.
 - [ ] Scaffold contract proof completed.
 
-<!-- Fill the fields below as plain label lines. Do not add list markers like "-" before labels. -->
-No-proof rationale:
-Non-edit assertion:
-Fail-fast input-contract proof:
-Generated-output viability proof:
+<!-- Fill the fields below on the same line as each label, or generate this section via `pnpm pr:readiness:prepare ...`. Do not add list markers like "-" before labels. -->
+No-proof rationale: 
+Non-edit assertion: 
+Fail-fast input-contract proof: 
+Generated-output viability proof: 

docs/guide/ztd-cli-quality-gates.md

@@ -70,6 +70,7 @@ The contract has three goals:
 
 The author-facing entry point is `.github/pull_request_template.md`.
 The enforcement point is `scripts/check-pr-readiness.js`, which reads the PR body from `GITHUB_EVENT_PATH`.
+For mechanical authoring, use `pnpm pr:readiness:prepare ...` to generate a validator-compatible body from the changed-file classification and structured field inputs before opening the PR.
 
 When scaffold-related files change, the PR body must cover:
 

package.json

@@ -34,6 +34,7 @@
     "playground:typecheck": "pnpm --filter ztd-playground typecheck",
     "playground:test": "pnpm --filter ztd-playground test",
     "prepare": "husky",
+    "pr:readiness:prepare": "node scripts/prepare-pr-readiness.js",
     "guard:branch-session": "node scripts/branch-session-guard.js",
     "verify:publish-readiness": "node scripts/publish-plan.mjs",
     "verify:publish-contract": "node scripts/verify-publish-contract.mjs",

packages/ztd-cli/tests/prReadiness.unit.test.ts

@@ -41,6 +41,41 @@ const {
     errors: string[];
   };
 };
+const {
+  buildPreparedPrReadiness,
+} = require('../../../scripts/prepare-pr-readiness.js') as {
+  buildPreparedPrReadiness(input: {
+    baseSha?: string | null;
+    headSha?: string | null;
+    changedFiles: string[];
+    summaryLines?: string[];
+    verificationLines?: string[];
+    baselineMode?: 'no-exception' | 'exception';
+    trackingIssue?: string;
+    scopedChecks?: string[];
+    baselineRationale?: string;
+    cliMode?: 'no-packet' | 'packet' | null;
+    cliNoMigrationRationale?: string;
+    upgradeNote?: string;
+    deprecationPlan?: string;
+    docsUpdated?: string;
+    releaseWording?: string;
+    scaffoldMode?: 'no-proof' | 'proof' | null;
+    noProofRationale?: string;
+    nonEditAssertion?: string;
+    failFastProof?: string;
+    generatedOutputProof?: string;
+  }): {
+    classification: {
+      changedFiles: string[];
+      requiresCliMigrationPacket: boolean;
+      requiresScaffoldContractProof: boolean;
+      cliMatchedFiles: string[];
+      scaffoldMatchedFiles: string[];
+    };
+    body: string;
+  };
+};
 
 function createBaseBody(): string {
   return [
@@ -249,3 +284,62 @@ test('pr-readiness classifies a changeset release branch as a release PR', () =>
     authorLogin: 'github-actions[bot]',
   });
 });
+
+test('pr-readiness preparation renders a validator-compatible CLI packet body', () => {
+  const prepared = buildPreparedPrReadiness({
+    changedFiles: ['packages/ztd-cli/src/commands/query.ts'],
+    summaryLines: ['align query flag migration guidance'],
+    verificationLines: ['pnpm --filter @rawsql-ts/ztd-cli test -- prReadiness.unit.test.ts'],
+    baselineMode: 'no-exception',
+    cliMode: 'packet',
+    upgradeNote: 'Replace `--specs-dir` with `--scope-dir` in command examples.',
+    deprecationPlan: 'Issue #746 tracks the deprecated alias removal.',
+    docsUpdated: 'CLI help output and guide examples were updated together.',
+    releaseWording: 'Call out the required flag rename in the release note.',
+  });
+
+  expect(prepared.body).toContain('Tracking issue: not needed; no baseline exception requested.');
+  expect(prepared.body).toContain('Upgrade note: Replace `--specs-dir` with `--scope-dir` in command examples.');
+
+  const validation = validatePrReadiness({
+    body: prepared.body,
+    classification: prepared.classification,
+  });
+
+  expect(validation.ok).toBe(true);
+  expect(validation.errors).toEqual([]);
+});
+
+test('pr-readiness preparation renders scaffold proof fields on the same line as labels', () => {
+  const prepared = buildPreparedPrReadiness({
+    changedFiles: ['packages/ztd-cli/templates/src/features/smoke/boundary.ts'],
+    summaryLines: ['mechanize scaffold proof authoring'],
+    verificationLines: ['pnpm --filter @rawsql-ts/ztd-cli test -- prReadiness.unit.test.ts'],
+    baselineMode: 'no-exception',
+    scaffoldMode: 'proof',
+    nonEditAssertion: 'The parent feature boundary remains untouched while the generated child import shape is asserted separately.',
+    failFastProof: 'The prepared body requires the explicit proof field before validation succeeds.',
+    generatedOutputProof: 'Generated project verification confirms the scaffolded output stays viable.',
+  });
+
+  expect(prepared.body).toContain('Non-edit assertion: The parent feature boundary remains untouched while the generated child import shape is asserted separately.');
+  expect(prepared.body).toContain('Fail-fast input-contract proof: The prepared body requires the explicit proof field before validation succeeds.');
+  expect(prepared.body).not.toContain('Non-edit assertion:\n');
+
+  const validation = validatePrReadiness({
+    body: prepared.body,
+    classification: prepared.classification,
+  });
+
+  expect(validation.ok).toBe(true);
+  expect(validation.errors).toEqual([]);
+});
+
+test('pr-readiness preparation fails fast when classified CLI changes omit a mode selection', () => {
+  expect(() => buildPreparedPrReadiness({
+    changedFiles: ['packages/ztd-cli/src/commands/query.ts'],
+    summaryLines: ['omit CLI mode to prove fail-fast guidance'],
+    verificationLines: ['pnpm --filter @rawsql-ts/ztd-cli test -- prReadiness.unit.test.ts'],
+    baselineMode: 'no-exception',
+  })).toThrow('CLI-facing changes require --cli-mode set to "no-packet" or "packet".');
+});

scripts/check-pr-readiness.js

@@ -353,6 +353,13 @@ if (require.main === module) {
 module.exports = {
   CLI_SURFACE_PATTERNS,
   SCAFFOLD_CONTRACT_PATTERNS,
+  MERGE_NO_EXCEPTION_LABEL,
+  MERGE_EXCEPTION_LABEL,
+  CLI_NO_PACKET_LABEL,
+  CLI_PACKET_LABEL,
+  SCAFFOLD_NO_PROOF_LABEL,
+  SCAFFOLD_PROOF_LABEL,
+  getChangedFiles,
   classifyPullRequestContext,
   classifyPrReadiness,
   validatePrReadiness,