@llman-sdd/core 0.3.1 → 0.5.1

package/src/report/specs.ts

@@ -1,8 +1,11 @@
 /**
- * Specs listing (peripheral-commands capability, r20/r21): morphology counts
- * aligned with v1 — rules = @human scenarios; enforced = rules carrying an
- * @req link that has an executable acceptance scenario; pending = the rest.
+ * Specs listing (peripheral-commands capability, r20/r21): morphology counts.
+ * Native model — rules = `规则:` blocks; enforced = rules with at least one
+ * nested executable scenario; pending = bare rules; acceptance = nested
+ * scenarios; featureScenarioCount = top-level feature-level examples.
  */
+import { renderMachine } from '../render/machine.ts';
+import { specIdOf } from '../spec/ir.ts';
 import type { CapabilityDoc } from '../spec/ir.ts';
 import type { SpecEntry } from '../validation/validate.ts';
 import { pad } from './collect.ts';
@@ -12,7 +15,7 @@ export interface SpecMorphology {
   ruleEnforcedCount: number;
   rulePendingCount: number;
   acceptanceCount: number;
-  orphanAcceptanceCount: number;
+  featureScenarioCount: number;
 }
 
 export interface SpecSummary {
@@ -27,35 +30,27 @@ export interface SpecSummary {
 }
 
 /** Morphology counts shared by `list --specs`, `show <spec> --json`, and the
- * CLI text render — the single source of the enforced/pending two-state rule
- * (rules = @human; enforced = @req-linked acceptance coverage; pending = rest). */
-export function morphologyOfScenarios(
-  scenarios: readonly { classification: string; reqIds: readonly string[] }[],
-): SpecMorphology {
-  const rules = scenarios.filter((s) => s.classification === 'human');
-  const acceptance = scenarios.filter((s) => s.classification === 'executable');
-  const acceptanceReqIds = new Set(acceptance.flatMap((s) => [...s.reqIds]));
-  const enforced = rules.filter((r) => r.reqIds.some((id) => acceptanceReqIds.has(id)));
-  const orphan = acceptance.filter((s) => s.reqIds.length === 0);
+ * CLI text render — rules with executable scenarios are enforced; bare rules
+ * without any nested scenario are pending; top-level examples are counted
+ * separately with no rule accounting. */
+export function morphologyOf(doc: CapabilityDoc): SpecMorphology {
+  const rules = doc.rules;
+  const acceptance = rules.flatMap((r) => r.scenarios);
   return {
     ruleCount: rules.length,
-    ruleEnforcedCount: enforced.length,
-    rulePendingCount: rules.length - enforced.length,
+    ruleEnforcedCount: rules.filter((r) => r.scenarios.length > 0).length,
+    rulePendingCount: rules.filter((r) => r.scenarios.length === 0).length,
     acceptanceCount: acceptance.length,
-    orphanAcceptanceCount: orphan.length,
+    featureScenarioCount: doc.orphans.length,
   };
 }
 
-function morphologyOf(doc: CapabilityDoc): SpecMorphology {
-  return morphologyOfScenarios(doc.scenarios);
-}
-
 export function collectSpecs(entries: readonly SpecEntry[]): SpecSummary[] {
   return entries.map((e) => {
     const morphology = morphologyOf(e.doc);
     return {
-      id: e.doc.header.capability ?? e.fileName,
-      title: e.doc.header.capability ?? e.fileName,
+      id: specIdOf(e),
+      title: specIdOf(e),
       purpose: e.doc.header.purpose ?? '',
       validScope: (e.doc.header.scope ?? '')
         .split(',')
@@ -81,6 +76,9 @@ export function renderSpecsList(summaries: readonly SpecSummary[]): string[] {
   return lines;
 }
 
-export function renderSpecsJson(summaries: readonly SpecSummary[]): string {
-  return JSON.stringify(summaries, null, 2);
+export function renderSpecsJson(
+  summaries: readonly SpecSummary[],
+  mode: 'json' | 'compact-json' | 'toon' = 'json',
+): string {
+  return renderMachine(summaries, mode);
 }

package/src/review/review.ts

@@ -1,12 +1,13 @@
 import type { GitLike } from '../git/spawnGit.ts';
+import { specIdOf } from '../spec/ir.ts';
 import { evaluateStaleness, notApplicableStaleness } from '../validation/staleness.ts';
 /**
  * Review aggregation (review-freeze capability, r23): five-signal review over
- * spec IR + validate sweep. Port of v1 sdd/review.rs observable contract.
+ * spec IR + validate sweep. Port of predecessor sdd/review.rs observable contract.
  */
 import { validateAllSpecs, type SpecEntry, type SpecIo } from '../validation/validate.ts';
 
-export type ReviewKind = 'pending' | 'unbound' | 'stale' | 'locked' | 'validate';
+export type ReviewKind = 'pending' | 'stale' | 'locked' | 'validate';
 
 export interface ReviewSignal {
   kind: ReviewKind;
@@ -15,25 +16,20 @@ export interface ReviewSignal {
   detail: string;
 }
 
-export interface TagBinding {
-  kind: 'tags';
-  tags: string[];
-}
-
 export interface ReviewInput {
   entries: readonly SpecEntry[];
-  /** config bdd.bindings (tags sources); null/empty = every acceptance unbound. */
-  bindings: readonly TagBinding[] | null;
   /** Active changes currently carrying a branch binding. */
   boundChangeCount: number;
   /** Active change summaries for the strict sweep (pending tasks → FAIL). */
   activeChanges?: readonly { name: string; completedTasks: number; totalTasks: number }[];
   /** Restrict per-capability signals (pending/unbound/stale) to this capability. */
   capability?: string;
-  /** git + root for real staleness evaluation (v1 parity). */
+  /** git + root for real staleness evaluation (predecessor parity). */
   git?: GitLike;
   root?: string;
   specsDir?: string;
+  /** predecessor base-ref override env value (LLMANSPEC_BASE_REF), injected by caller. */
+  baseRefEnv?: string;
 }
 
 export interface ReviewResult {
@@ -43,6 +39,15 @@ export interface ReviewResult {
   exitCode: number;
 }
 
+/**
+ * Root-relative spec path for staleness (`specRel` contract): repo-root
+ * discovery yields `llmanspec/…` paths while bare stems get the specs prefix.
+ * Shared with the CLI's spec validate path.
+ */
+export function specRelFor(fileName: string): string {
+  return fileName.startsWith('llmanspec/') ? fileName : `llmanspec/specs/${fileName}`;
+}
+
 export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
   const { entries, boundChangeCount } = input;
   const strictChangeFails = (input.activeChanges ?? []).filter(
@@ -57,32 +62,29 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
   const sorted = [...entries].toSorted((a, b) => a.fileName.localeCompare(b.fileName));
 
   for (const entry of sorted) {
-    const cap = entry.doc.header.capability ?? entry.fileName;
+    const cap = specIdOf(entry);
     // r33: per-capability signals honor the --capability filter; locked and
     // validate stay global regardless.
     if (input.capability !== undefined && cap !== input.capability) continue;
-    const rules = entry.doc.scenarios.filter((s) => s.classification === 'human');
-    const acceptance = entry.doc.scenarios.filter((s) => s.classification === 'executable');
-    const acceptanceReqIds = new Set(acceptance.flatMap((s) => s.reqIds));
-    const pending = rules.filter((r) => !r.reqIds.some((id) => acceptanceReqIds.has(id)));
-    // v1 r5: unbound = orphan acceptance scenarios (no @req link).
-    const unbound = acceptance.filter((s) => s.reqIds.length === 0);
+    // Native model: rules are `规则:` blocks; a rule without nested scenarios
+    // is "bare" (pending — candidate for conversion/compaction). Top-level
+    // scenarios outside any rule are plain feature-level examples with no
+    // special signal.
+    const pending = entry.doc.rules.filter((r) => r.scenarios.length === 0);
 
     push('pending', cap, pending.length);
-    push('unbound', cap, unbound.length);
 
-    // staleness (v1 evaluate): real base-ref/scope evaluation.
+    // staleness (predecessor evaluate): real base-ref/scope evaluation.
     let staleInfo = notApplicableStaleness();
     let staleCount = 0;
     if (input.git !== undefined && input.root !== undefined) {
-      const specRel =
-        (entry.fileName.startsWith('llmanspec/') ? '' : 'llmanspec/specs/') + entry.fileName;
+      const specRel = specRelFor(entry.fileName);
       const evalResult = evaluateStaleness({
         git: input.git,
         root: input.root,
         specRel,
         scope: entry.doc.header.scope?.split(',').map((x) => x.trim()) ?? [],
-        baseRefEnv: process.env.LLMANSPEC_BASE_REF,
+        baseRefEnv: input.baseRefEnv,
       });
       staleInfo = evalResult.info;
       staleCount = staleInfo.status === 'OK' || staleInfo.status === 'NOTAPPLICABLE' ? 0 : 1;
@@ -91,7 +93,8 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
   }
 
   const failed = sweep.verdicts.filter((v) => !v.ok);
-  // v1 sweep = `validate --all --strict --no-check`: pending tasks escalate a
+  const sweepFailedCount = failed.length;
+  // predecessor sweep = `validate --all --strict --no-check`: pending tasks escalate a
   // change to FAIL, and that feeds the review critical count.
   for (const c of strictChangeFails) {
     failed.push({
@@ -107,19 +110,30 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
       ],
     });
   }
-  // v1 parity: `count` is the removed locked-rule-confirmation concept (always
+  // predecessor parity: `count` is the removed locked-rule-confirmation concept (always
   // 0 now); the detail text carries the bound-change count separately.
   push(
     'locked',
     '-',
     0,
-    `${boundChangeCount} bound change(s); inspect with \`llman sdd change diff <id>\``,
+    `${boundChangeCount} bound change(s); inspect with \`llman-sdd change diff <id>\``,
   );
+  // detail names the failing source: sweep failures point at `validate --all`;
+  // strict-only failures name the offending changes instead of a command that
+  // would report green.
+  const sweepDetail =
+    sweepFailedCount > 0 ? 'validate --all failed; run `llman-sdd validate --all` for details' : '';
+  const strictDetail =
+    strictChangeFails.length > 0
+      ? `${strictChangeFails.length} active change(s) with unchecked tasks: ${strictChangeFails
+          .map((c) => `${c.name} (${c.totalTasks - c.completedTasks} unchecked)`)
+          .join(', ')}`
+      : '';
   push(
     'validate',
     '-',
     failed.length,
-    failed.length > 0 ? 'validate --all failed; run `llman sdd validate --all` for details' : 'ok',
+    [sweepDetail, strictDetail].filter(Boolean).join('; ') || 'ok',
   );
 
   const warningCount = signals
@@ -128,8 +142,8 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
   const criticalCount = failed.length;
 
   const lines: string[] = [`Review: critical=${criticalCount} warning=${warningCount}`];
-  for (const cap of sorted.map((e) => e.doc.header.capability ?? e.fileName)) {
-    for (const kind of ['pending', 'unbound', 'stale'] as const) {
+  for (const cap of sorted.map((e) => specIdOf(e))) {
+    for (const kind of ['pending', 'stale'] as const) {
       const s = signals.find((x) => x.kind === kind && x.capability === cap);
       if (!s) continue;
       lines.push(`${kind}: ${cap} (${s.count})`);
@@ -151,7 +165,7 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
   };
 }
 
-/** `review --export-html`: fill the v1 shared/review.html template (pure —
+/** `review --export-html`: fill the predecessor shared/review.html template (pure —
  * callers read the template; CLI passes it via core's TEMPLATES_ROOT). */
 export function renderReviewHtml(
   template: string,
@@ -159,6 +173,7 @@ export function renderReviewHtml(
     signals: readonly { kind: string; capability: string; count: number; detail: string }[];
     summary: { criticalCount: number; warningCount: number };
   },
+  now: Date,
 ): string {
   const esc = (input: string): string =>
     input
@@ -180,5 +195,5 @@ export function renderReviewHtml(
     .replaceAll('__WARNING__', String(result.summary.warningCount))
     .replaceAll('__SIGNALS__', JSON.stringify(sigJson))
     .replaceAll('__MERMAID__', mermaid)
-    .replaceAll('__GENERATED__', new Date().toISOString());
+    .replaceAll('__GENERATED__', now.toISOString());
 }

package/src/spec/authoring.ts

@@ -1,13 +1,15 @@
 /**
- * Programming-style spec authoring helpers (r41-r43, v1 parity):
- * append rules / acceptance scenarios, resolve req ids, dedupe conflicts.
+ * Programming-style spec authoring helpers (r41-r43, native v2):
+ * append `规则:` blocks / nested scenarios, resolve req ids, dedupe conflicts.
  * Appends are text-level so existing file content (formatting, comments)
  * stays untouched.
  */
 
-import type { CapabilityDoc } from './ir.ts';
-
-const RULE_KEYWORDS = ['MUST', 'SHALL', '必须', '不得', '禁止'] as const;
+import type { CapabilityDoc, RuleIR } from './ir.ts';
+import { specIdOf } from './ir.ts';
+import { BLOCK_KEYWORD_LINE_RE, officialKeywordsOrEn } from './keywords.ts';
+import { sourceDialect } from './parser.ts';
+import type { RegistryDuplicate } from './reqRegistry.ts';
 
 export class AuthoringError extends Error {}
 
@@ -22,60 +24,49 @@ export interface WriteIo {
   writeText(path: string, content: string): void;
 }
 
-function keywordsOf(content: string): {
+interface KeywordSet {
+  rule: string;
   scenario: string;
   given: string;
   when: string;
   thenText: string;
-} {
-  return content.includes('功能:')
-    ? { scenario: '场景', given: '假如', when: '当', thenText: '那么' }
-    : { scenario: 'Scenario', given: 'Given', when: 'When', thenText: 'Then' };
 }
 
-function assertRuleWording(statement: string): void {
-  if (!RULE_KEYWORDS.some((k) => statement.includes(k))) {
-    throw new AuthoringError(
-      `statement must contain a rule keyword (${RULE_KEYWORDS.join('/')}): ${statement}`,
-    );
-  }
+function keywordsOf(content: string): KeywordSet {
+  const kw = officialKeywordsOrEn(sourceDialect(content));
+  return {
+    rule: kw.rule,
+    scenario: kw.scenario,
+    given: kw.given,
+    when: kw.when,
+    thenText: kw.thenText,
+  };
 }
 
-function findReq(
+function findRule(
   entries: readonly SpecEntryLike[],
   reqId: string,
-): { entry: SpecEntryLike; scenarioName: string; statement: string } | null {
+): { entry: SpecEntryLike; rule: RuleIR } | null {
   for (const entry of entries) {
-    for (const scenario of entry.doc.scenarios) {
-      if (scenario.reqIds.includes(reqId) && scenario.classification === 'human') {
-        return { entry, scenarioName: scenario.name, statement: scenario.statement };
-      }
-    }
+    const rule = entry.doc.rules.find((r) => r.reqId === reqId);
+    if (rule !== undefined) return { entry, rule };
   }
   return null;
 }
 
-/** v1 parity: only @human (rule) req ids participate in the dedupe registry. */
+/** Requirement handles (`@req` on `规则:` headers) participate in the dedupe registry. */
 export function ruleReqIds(entries: readonly SpecEntryLike[]): Set<string> {
   const ids = new Set<string>();
   for (const entry of entries) {
-    for (const scenario of entry.doc.scenarios) {
-      if (scenario.classification === 'human') {
-        for (const id of scenario.reqIds) ids.add(id);
-      }
+    for (const rule of entry.doc.rules) {
+      if (rule.reqId !== '') ids.add(rule.reqId);
     }
   }
   return ids;
 }
 
 export function allReqIds(entries: readonly SpecEntryLike[]): Set<string> {
-  const ids = new Set<string>();
-  for (const entry of entries) {
-    for (const scenario of entry.doc.scenarios) {
-      for (const id of scenario.reqIds) ids.add(id);
-    }
-  }
-  return ids;
+  return ruleReqIds(entries);
 }
 
 export interface AddReqOpts {
@@ -85,21 +76,43 @@ export interface AddReqOpts {
   statement: string;
 }
 
-/** Append `@req:<id> @human` rule scenario to `<capability>.feature` (r41). */
+/**
+ * Single write-target caliber (matches the spec show read side): the flat
+ * `specs/<capability>.feature` wins when present, else the discovered entry
+ * whose specId equals the capability exactly (covers directory-style
+ * `<capability>/<capability>.feature`); the flat path is returned unchanged
+ * when neither exists so callers raise their usual not-found error.
+ */
+export function resolveWriteTarget(
+  io: WriteIo,
+  specsRoot: string,
+  capability: string,
+  entries: readonly SpecEntryLike[],
+): string {
+  const flat = `${specsRoot}/${capability}.feature`;
+  if (io.exists(flat)) return flat;
+  const hit = entries.find((entry) => specIdOf(entry) === capability);
+  return hit !== undefined ? hit.fileName : flat;
+}
+
+/** Append a `规则:` block (with @req handle) to the resolved target spec (r41). */
 export function addReq(
   io: WriteIo,
   specsRoot: string,
   entries: readonly SpecEntryLike[],
   opts: AddReqOpts,
 ): string {
-  const path = `${specsRoot}/${opts.capability}.feature`;
+  const path = resolveWriteTarget(io, specsRoot, opts.capability, entries);
   if (!io.exists(path)) throw new AuthoringError(`spec not found: ${path}`);
   if (allReqIds(entries).has(opts.reqId)) {
     throw new AuthoringError(`req id already in use: ${opts.reqId}`);
   }
-  assertRuleWording(opts.statement);
   const kw = keywordsOf(io.readText(path));
-  const block = `\n  @req:${opts.reqId} @human\n  ${kw.scenario}: ${opts.title}\n    ${opts.statement}\n`;
+  const desc = opts.statement
+    .split('\n')
+    .map((l) => `    ${l.trim()}`)
+    .join('\n');
+  const block = `\n  @req:${opts.reqId}\n  ${kw.rule}: ${opts.title}\n${desc}\n`;
   io.writeText(path, `${io.readText(path).replace(/\n+$/u, '')}${block}`);
   return path;
 }
@@ -113,25 +126,48 @@ export interface AddScenarioOpts {
   thenText: string;
 }
 
-/** Append `@req:<id> @executable` acceptance scenario (r42). */
+/**
+ * Insert a nested `场景:` under the target rule's block (r42). Finds the
+ * rule block boundary in the raw text (next 2-space top-level element) and
+ * inserts the scenario before it, keeping existing formatting untouched.
+ */
 export function addScenario(
   io: WriteIo,
   specsRoot: string,
   entries: readonly SpecEntryLike[],
   opts: AddScenarioOpts,
 ): string {
-  const path = `${specsRoot}/${opts.capability}.feature`;
+  const path = resolveWriteTarget(io, specsRoot, opts.capability, entries);
   if (!io.exists(path)) throw new AuthoringError(`spec not found: ${path}`);
-  if (findReq(entries, opts.reqId) === null) {
-    throw new AuthoringError(`req id not found: ${opts.reqId}`);
+  const found = findRule(entries, opts.reqId);
+  if (found === null) throw new AuthoringError(`req id not found: ${opts.reqId}`);
+  const content = io.readText(path);
+  const lines = content.split('\n');
+  const tagIdx = lines.findIndex((l) => l.trim() === `@req:${opts.reqId}`);
+  if (tagIdx === -1) throw new AuthoringError(`req id not found in file: ${opts.reqId}`);
+  // block end = first line after the tag's own rule header at 2-space top-level
+  // indent that is a tag line or an official block keyword line (2-space +
+  // keyword immediately, any official dialect). The rule header directly
+  // following the tag opens the block, so the scan starts after it — otherwise
+  // the header itself is mistaken for the boundary and the scenario is
+  // inserted before the rule line (broken output).
+  let end = lines.length;
+  for (let i = tagIdx + 2; i < lines.length; i++) {
+    const l = lines[i] ?? '';
+    if (l.startsWith('  @') || BLOCK_KEYWORD_LINE_RE.test(l)) {
+      end = i;
+      break;
+    }
   }
-  const kw = keywordsOf(io.readText(path));
+  const kw = keywordsOf(content);
   const givenLine =
-    opts.given !== undefined && opts.given !== '' ? `    ${kw.given} ${opts.given}\n` : '';
-  const block =
-    `\n  @req:${opts.reqId} @executable\n  ${kw.scenario}: ${opts.scenarioId}\n` +
-    `${givenLine}    ${kw.when} ${opts.when}\n    ${kw.thenText} ${opts.thenText}\n`;
-  io.writeText(path, `${io.readText(path).replace(/\n+$/u, '')}${block}`);
+    opts.given !== undefined && opts.given !== '' ? `      ${kw.given} ${opts.given}\n` : '';
+  const scenarioBlock =
+    `    ${kw.scenario}: ${opts.scenarioId}\n` +
+    `${givenLine}      ${kw.when} ${opts.when}\n      ${kw.thenText} ${opts.thenText}\n`;
+  // insert with a leading blank separator so the file stays readable
+  lines.splice(end, 0, '', scenarioBlock.trimEnd());
+  io.writeText(path, lines.join('\n'));
   return path;
 }
 
@@ -145,37 +181,60 @@ export interface ResolvedReq {
 
 /** Resolve an rN to capability/statement plus bound harness scenarios (r43). */
 export function resolveReq(entries: readonly SpecEntryLike[], reqId: string): ResolvedReq | null {
-  const rule = findReq(entries, reqId);
-  if (rule === null) return null;
-  const capability =
-    rule.entry.doc.header.capability ?? rule.entry.fileName.replace(/\.feature$/u, '');
-  const harness: string[] = [];
-  for (const entry of entries) {
-    for (const scenario of entry.doc.scenarios) {
-      if (scenario.classification === 'executable' && scenario.reqIds.includes(reqId)) {
-        harness.push(`${entry.fileName}:${scenario.name}`);
-      }
-    }
-  }
-  return { reqId, capability, title: rule.scenarioName, statement: rule.statement, harness };
+  const found = findRule(entries, reqId);
+  if (found === null) return null;
+  const { entry, rule } = found;
+  const harness = rule.scenarios.map((s) => `${entry.fileName}:${s.name}`);
+  return {
+    reqId,
+    capability: specIdOf(entry),
+    title: rule.title,
+    statement: rule.description,
+    harness,
+  };
 }
 
 export interface DedupePlanItem {
   reqId: string;
+  /** File of the kept (first) occurrence. */
   keepFile: string;
   remapFile: string;
   newReqId: string;
+  /** 1-based ordinal of the remapped `@req:<id>` occurrence within remapFile's text. */
+  occurrenceOrdinal: number;
 }
 
 /**
- * Plan (and optionally apply) a re-map of globally duplicated rN ids: the
- * first file keeps the id, later files get the next free id (r43).
+ * Replace the ordinal-th `@req:<id>` tag in raw text. The tag match is
+ * boundary-exact (`@req:r1` never matches inside `@req:r10`), and only the
+ * target ordinal is rewritten so a kept first occurrence in the same file
+ * stays untouched (r43: 按出现顺序首现保留、其余出现逐个重取号).
+ */
+function replaceNthReqTag(
+  content: string,
+  reqId: string,
+  newReqId: string,
+  ordinal: number,
+): string {
+  const pattern = new RegExp(`@req:${reqId}(?!\\d)`, 'gu');
+  let seen = 0;
+  return content.replace(pattern, (tag) => {
+    seen += 1;
+    return seen === ordinal ? `@req:${newReqId}` : tag;
+  });
+}
+
+/**
+ * Plan (and optionally apply) a re-map of globally duplicated rN ids
+ * (r43: 同文件内共用或跨文件,按出现顺序首现保留、其余出现逐个重取号).
+ * `apply: false` (`--dry-run`) returns the plan without writing anything.
  */
 export function planDedupe(
   entries: readonly SpecEntryLike[],
   io: WriteIo,
   specsRoot: string,
-  duplicates: readonly { reqId: string; files: string[] }[],
+  duplicates: readonly RegistryDuplicate[],
+  opts: { apply?: boolean } = {},
 ): DedupePlanItem[] {
   const used = ruleReqIds(entries);
   let next = 1;
@@ -186,21 +245,38 @@ export function planDedupe(
   };
   const plan: DedupePlanItem[] = [];
   for (const dup of duplicates) {
-    const [keep, ...rest] = dup.files;
-    for (const remapFile of rest) {
-      const newReqId = fresh();
-      if (keep !== undefined) {
-        plan.push({ reqId: dup.reqId, keepFile: keep, remapFile, newReqId });
+    // occurrences are in scan order (sorted files, in-file rule order); the
+    // per-file ordinal counts every occurrence so kept ones hold their slot
+    // in the text and remapped ones target the exact `@req:` tag to rewrite.
+    const perFileOrdinal = new Map<string, number>();
+    let keepFile: string | null = null;
+    for (const occ of dup.occurrences) {
+      const ordinal = (perFileOrdinal.get(occ.fileName) ?? 0) + 1;
+      perFileOrdinal.set(occ.fileName, ordinal);
+      if (keepFile === null) {
+        keepFile = occ.fileName;
+        continue;
       }
+      plan.push({
+        reqId: dup.reqId,
+        keepFile,
+        remapFile: occ.fileName,
+        newReqId: fresh(),
+        occurrenceOrdinal: ordinal,
+      });
     }
   }
+  if (opts.apply === false) return plan;
   for (const item of plan) {
     // registry duplicates carry bare file names; accept already-rooted paths too
     const path = item.remapFile.startsWith(`${specsRoot}/`)
       ? item.remapFile
       : `${specsRoot}/${item.remapFile}`;
     const content = io.readText(path);
-    io.writeText(path, content.replaceAll(`@req:${item.reqId}`, `@req:${item.newReqId}`));
+    io.writeText(
+      path,
+      replaceNthReqTag(content, item.reqId, item.newReqId, item.occurrenceOrdinal),
+    );
   }
   return plan;
 }