dropped --pr arg, list changed files, support multi-file seps w url override

Author: pcarleton

.claude/skills/new-sep/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   conformance repo from a SEP PR's spec diff. Runs the new-sep CLI, then
   parses the modelcontextprotocol/modelcontextprotocol spec diff to populate
   `requirements[]` with the RFC 2119 sentences and proposed check IDs.
-argument-hint: '<sep-number> [--pr <num>] [--target client|server|authorization-server]'
+argument-hint: '<sep-number> [--target client|server|authorization-server]'
 ---
 
 # new-sep: SEP traceability YAML scaffolding
@@ -36,8 +36,7 @@ The name should be `@modelcontextprotocol/conformance`. If not, stop and ask the
 
 Extract from the user's input:
 
-- **sep-number** (required): the SEP number, e.g. `2164`.
-- **--pr <num>** (optional): the PR number in `modelcontextprotocol/modelcontextprotocol`. If omitted, the CLI searches for a PR titled `SEP-<NNNN>` and fails loudly on 0 or >1 hits.
+- **sep-number** (required): the SEP number, e.g. `2164`. This is also the PR number in `modelcontextprotocol/modelcontextprotocol` by convention.
 - **--target client|server|authorization-server** (optional): which scenarios subdirectory to write to. Inferred from the spec path if omitted.
 
 ## Step 2: Generate the skeleton
@@ -46,22 +45,21 @@ Run the CLI:
 
 ```bash
 npm run --silent build
-node dist/index.js new-sep <NNNN> [--pr <num>] [--target <target>]
+node dist/index.js new-sep <NNNN> [--target <target>]
 ```
 
 (For development against a non-built source tree: `npx tsx src/index.ts new-sep ...`.)
 
 The CLI writes `src/scenarios/<target>/sep-<NNNN>.yaml` with `sep`, `spec_url`, and two TODO `requirements[]` rows. Capture the output path from the CLI's `Wrote …` line and remember it as `$YAML`.
 
-If the CLI errors with "No PRs match" or "Multiple PRs match", read the message, ask the user for the right `--pr <num>`, and rerun. Do not guess.
+If the CLI errors with "does not change any docs/specification/draft/\*.mdx", the SEP's spec changes landed in a separate PR — ask the user for the spec file path and rerun with `--spec-path docs/specification/draft/<path>`. Do not guess.
 
 ## Step 3: Fetch the spec diff
 
 `AGENTS.md` (lines 64–72) is explicit that severity must come from the spec text itself, not the SEP markdown or the conformance PR description:
 
 ```bash
-PR=$(node dist/index.js new-sep <NNNN> --help >/dev/null 2>&1; echo <pr-from-step-2>)
-gh api "repos/modelcontextprotocol/modelcontextprotocol/pulls/$PR/files" \
+gh api "repos/modelcontextprotocol/modelcontextprotocol/pulls/<NNNN>/files" \
   --jq '.[] | select(.filename | test("^docs/specification/draft/.*\\.mdx$")) | {filename, patch}'
 ```
 
@@ -110,6 +108,16 @@ If a requirement is ambiguous or you're not confident, leave it as a `TODO:` row
 
 Also fix the `spec_url`: the CLI emits the page URL with no anchor. If the requirements you extracted live under a specific spec subsection (e.g. `#error-handling`), append it.
 
+If a requirement comes from a **different spec page** than `spec_url` (the SEP touched multiple `.mdx` files — the CLI prints these as "PR also changes N other spec file(s)"), give that row a full `url:` override:
+
+```yaml
+- text: '...'
+  check: sep-NNNN-slug
+  url: https://modelcontextprotocol.io/specification/draft/other/page#anchor
+```
+
+A row's effective spec reference is `row.url ?? file.spec_url`.
+
 Write the result back to `$YAML`.
 
 ## Step 7: Hand-off

AGENTS.md

@@ -79,7 +79,7 @@ Scaffold the requirement-traceability YAML with:
 npx @modelcontextprotocol/conformance new-sep <NNNN>
 ```
 
-The command searches `modelcontextprotocol/modelcontextprotocol` for a PR titled `SEP-<NNNN>`, derives `spec_url` from the `docs/specification/draft/*.mdx` file it changes, picks `src/scenarios/{client,server,authorization-server}/` from the spec path, and writes `sep-<NNNN>.yaml` with TODO `requirements[]` rows. Use `--spec-url`, `--spec-path`, or `--pr` to override the lookup when title search is ambiguous. The `new-sep` Claude Code skill drives the same flow end-to-end, parses the spec diff, and fills in the requirement rows.
+The command looks up PR #`<NNNN>` in `modelcontextprotocol/modelcontextprotocol` (SEP numbers are PR numbers), derives `spec_url` from the `docs/specification/draft/*.mdx` file it changes, picks `src/scenarios/{client,server,authorization-server}/` from the spec path, and writes `sep-<NNNN>.yaml` with TODO `requirements[]` rows. Use `--spec-path` or `--spec-url` to skip the lookup. The `new-sep` Claude Code skill drives the same flow end-to-end, parses the spec diff, and fills in the requirement rows.
 
 ## Examples: prove it passes and fails
 

src/new-sep/index.test.ts

@@ -109,6 +109,32 @@ requirements:
     );
   });
 
+  it('emits per-row url: overrides', () => {
+    const out = renderYaml({
+      sep: 1234,
+      specUrl: 'https://modelcontextprotocol.io/specification/draft/server/a',
+      requirements: [
+        { text: 'from primary file', check: 'sep-1234-a' },
+        {
+          text: 'from secondary file',
+          check: 'sep-1234-b',
+          url: 'https://modelcontextprotocol.io/specification/draft/server/b#x'
+        }
+      ]
+    });
+    expect(out).toBe(
+      `sep: 1234
+spec_url: https://modelcontextprotocol.io/specification/draft/server/a
+requirements:
+  - text: 'from primary file'
+    check: sep-1234-a
+  - text: 'from secondary file'
+    check: sep-1234-b
+    url: https://modelcontextprotocol.io/specification/draft/server/b#x
+`
+    );
+  });
+
   it('escapes single quotes by doubling them', () => {
     const out = renderYaml({
       sep: 1,

src/new-sep/index.ts

@@ -10,6 +10,8 @@ export interface RequirementRow {
   check?: string;
   excluded?: string;
   issue?: string;
+  /** Full spec URL for this requirement; overrides the file-level spec_url. */
+  url?: string;
 }
 
 const TARGET_DIRS: Record<Target, string> = {
@@ -81,6 +83,7 @@ export function renderYaml(input: {
       lines.push(`    excluded: '${escapeSingleQuoted(r.excluded)}'`);
     }
     if (r.issue) lines.push(`    issue: ${r.issue}`);
+    if (r.url) lines.push(`    url: ${r.url}`);
   }
   return lines.join('\n') + '\n';
 }
@@ -105,38 +108,17 @@ interface SpecCandidate {
 
 async function lookupSpecPath(args: {
   sep: number;
-  pr?: number;
   repo: string;
   token: string;
-}): Promise<string> {
+}): Promise<string[]> {
   const [owner, repoName] = args.repo.split('/');
   if (!owner || !repoName) {
     throw new Error(`Invalid --repo: ${args.repo} (expected owner/repo)`);
   }
   const octokit = new Octokit({ auth: args.token });
 
-  let prNumber = args.pr;
-  if (!prNumber) {
-    const q = `repo:${args.repo} type:pr SEP-${args.sep} in:title`;
-    const res = await octokit.search.issuesAndPullRequests({ q });
-    if (res.data.total_count === 0) {
-      throw new Error(
-        `No PRs in ${args.repo} matching "SEP-${args.sep}" in title. ` +
-          `Pass --pr <num> to disambiguate.`
-      );
-    }
-    if (res.data.total_count > 1) {
-      const candidates = res.data.items
-        .slice(0, 5)
-        .map((i) => `  #${i.number}  ${i.title}`)
-        .join('\n');
-      throw new Error(
-        `Multiple PRs in ${args.repo} match "SEP-${args.sep}":\n${candidates}\n` +
-          `Pass --pr <num> to pick one.`
-      );
-    }
-    prNumber = res.data.items[0].number;
-  }
+  // SEP numbers are PR numbers in the spec repo by convention.
+  const prNumber = args.sep;
 
   const files = await octokit.paginate(octokit.pulls.listFiles, {
     owner,
@@ -158,24 +140,8 @@ async function lookupSpecPath(args: {
         `${SPEC_PATH_PREFIX}*.mdx file. Pass --spec-path <path> to override.`
     );
   }
-  if (candidates.length === 1) {
-    return candidates[0].filename;
-  }
   candidates.sort((a, b) => b.additions - a.additions);
-  if (candidates[0].additions > candidates[1].additions) {
-    console.error(
-      `Multiple spec files changed; picking ${candidates[0].filename} ` +
-        `(most additions).`
-    );
-    return candidates[0].filename;
-  }
-  const list = candidates
-    .map((c) => `  ${c.filename}  (+${c.additions})`)
-    .join('\n');
-  throw new Error(
-    `Multiple spec files changed with equal weight in PR #${prNumber}:\n${list}\n` +
-      `Pass --spec-path <path> to pick one.`
-  );
+  return candidates.map((c) => c.filename);
 }
 
 export function createNewSepCommand(): Command {
@@ -196,7 +162,6 @@ export function createNewSepCommand(): Command {
       '--spec-path <path>',
       `${SPEC_PATH_PREFIX}... path to derive spec_url from (skips GitHub lookup)`
     )
-    .option('--pr <num>', 'PR number in the spec repo (skips title search)')
     .option(
       '--repo <owner/repo>',
       'Spec repo to query for the SEP PR',
@@ -228,6 +193,7 @@ export function createNewSepCommand(): Command {
 
       let specUrl: string | undefined = options.specUrl;
       let specPath: string | undefined = options.specPath;
+      let otherSpecPaths: string[] = [];
 
       if (!specUrl && !specPath) {
         const token = await resolveToken(options.token);
@@ -242,12 +208,13 @@ export function createNewSepCommand(): Command {
           process.exit(1);
         }
         try {
-          specPath = await lookupSpecPath({
+          const specPaths = await lookupSpecPath({
             sep,
-            pr: options.pr ? parseInt(options.pr, 10) : undefined,
             repo: options.repo,
             token
           });
+          specPath = specPaths[0];
+          otherSpecPaths = specPaths.slice(1);
           console.error(`Resolved spec path: ${specPath}`);
         } catch (err) {
           console.error((err as Error).message);
@@ -306,6 +273,17 @@ export function createNewSepCommand(): Command {
       await fs.writeFile(outPath, yaml, 'utf-8');
 
       console.error(`Wrote ${outPath}`);
+      if (otherSpecPaths.length > 0) {
+        console.error(
+          `Note: PR also changes ${otherSpecPaths.length} other spec file(s):`
+        );
+        for (const p of otherSpecPaths) {
+          console.error(`  ${specPathToUrl(p)}`);
+        }
+        console.error(
+          `  Use a per-row "url:" for requirements from those files.`
+        );
+      }
       console.error('Next steps:');
       console.error(
         '  1. Edit the file to quote real normative sentences from the spec diff'