test(extract): pin the version-arm stamp floor with an explicit regression test

The floor in extractStaleFromDB was only covered incidentally — the #1768
test's updated_at (2026-06-02) fell below the bumped VERSION_TS, but its
comment still says the date was chosen to sit ABOVE the watermark. A future
date 'repair' there would silently drop floor coverage. This test pins it
directly: pre-watermark page clears after --stale and stays cleared.
Verified fail-without-fix against master's extract.ts.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/commands/backlinks.ts

@@ -5,8 +5,8 @@
  * checks if back-links exist, and optionally creates them.
  *
  * Usage:
- *   gbrain check-backlinks check [dir] [--dir <brain-dir>] # report missing back-links
- *   gbrain check-backlinks fix [dir] [--dir <brain-dir>]   # create missing back-links
+ *   gbrain check-backlinks check [--dir <brain-dir>]     # report missing back-links
+ *   gbrain check-backlinks fix [--dir <brain-dir>]        # create missing back-links
  *   gbrain check-backlinks fix --dry-run                  # preview fixes
  */
 
@@ -201,40 +201,6 @@ export interface BacklinksResult {
   dryRun: boolean;
 }
 
-export interface ParsedBacklinksArgs {
-  subcommand: string | undefined;
-  brainDir: string;
-  dryRun: boolean;
-}
-
-export function parseBacklinksArgs(args: string[]): ParsedBacklinksArgs {
-  const subcommand = args[0];
-  const dryRun = args.includes('--dry-run');
-  const dirIdx = args.indexOf('--dir');
-  const flagDir = dirIdx >= 0 && args[dirIdx + 1] && !args[dirIdx + 1].startsWith('--')
-    ? args[dirIdx + 1]
-    : undefined;
-
-  let positionalDir: string | undefined;
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === '--dir') {
-      i++;
-      continue;
-    }
-    if (arg === '--dry-run') continue;
-    if (arg.startsWith('--')) continue;
-    positionalDir = arg;
-    break;
-  }
-
-  return {
-    subcommand,
-    brainDir: flagDir ?? positionalDir ?? '.',
-    dryRun,
-  };
-}
-
 /**
  * Library-level backlinks check/fix. Throws on validation errors; returns a
  * structured result so Minions handlers + autopilot-cycle can surface counts.
@@ -270,14 +236,16 @@ export async function runBacklinksCore(opts: BacklinksOpts): Promise<BacklinksRe
 }
 
 export async function runBacklinks(args: string[]) {
-  const { subcommand, brainDir, dryRun } = parseBacklinksArgs(args);
+  const subcommand = args[0];
+  const dirIdx = args.indexOf('--dir');
+  const brainDir = dirIdx >= 0 ? args[dirIdx + 1] : '.';
+  const dryRun = args.includes('--dry-run');
 
   if (!subcommand || !['check', 'fix'].includes(subcommand)) {
-    console.error('Usage: gbrain check-backlinks <check|fix> [dir] [--dir <brain-dir>] [--dry-run]');
+    console.error('Usage: gbrain check-backlinks <check|fix> [--dir <brain-dir>] [--dry-run]');
     console.error('  check    Report missing back-links');
     console.error('  fix      Create missing back-links (appends to Timeline)');
-    console.error('  dir      Brain directory (default: current directory)');
-    console.error('  --dir    Brain directory override');
+    console.error('  --dir    Brain directory (default: current directory)');
     console.error('  --dry-run  Preview fixes without writing');
     process.exit(1);
   }

src/commands/extract.ts

@@ -1743,7 +1743,15 @@ async function extractStaleFromDB(
       // `page.updated_at.toISOString()` — the JS Date is ms-truncated, so the
       // µs-precision DB updated_at stayed strictly greater and the page never
       // cleared on Postgres. Stamping the exact value makes them equal.
-      processedRefs.push({ slug: page.slug, source_id: page.source_id, extractedAt: page.updated_at_iso });
+      //
+      // Version-arm floor: a page last edited BEFORE LINK_EXTRACTOR_VERSION_TS
+      // would otherwise be stamped below the version watermark and stay
+      // permanently stale (`links_extracted_at < versionTs` re-fires every run).
+      // Stamp max(updated_at, versionTs) — versionTs is always a past release
+      // date, so a concurrent edit's now() still exceeds the stamp and D4 holds.
+      // Tie at ms precision picks updated_at_iso (its µs ≥ versionTs's .000000).
+      const stampTs = new Date(page.updated_at_iso) >= new Date(versionTs) ? page.updated_at_iso : versionTs;
+      processedRefs.push({ slug: page.slug, source_id: page.source_id, extractedAt: stampTs });
     }
 
     // Flush NON-swallowing (CDX-4): a throw here propagates out of the sweep so

src/core/link-extraction.ts

@@ -28,7 +28,7 @@ import { ensureWellFormed } from './text-safe.ts';
  * OR updated_at > links_extracted_at`. It is an ISO-8601 string (NOT a number) —
  * the column is TIMESTAMPTZ and the predicate binds it as `::timestamptz`.
  */
-export const LINK_EXTRACTOR_VERSION_TS = '2026-05-31T00:00:00Z';
+export const LINK_EXTRACTOR_VERSION_TS = '2026-07-21T00:00:00Z';
 
 // ─── Entity references ──────────────────────────────────────────
 
@@ -80,10 +80,10 @@ export type LinkResolutionType = 'qualified' | 'unqualified';
  * Directory prefix whitelist. These are the top-level slug dirs the extractor
  * recognizes as entity references. Upstream canonical + our extensions:
  *   - Gbrain canonical: people, companies, meetings, concepts, deal, civic, project, source, media, yc, projects
- *   - Our domain extensions: tech, finance, personal, openclaw (domain-organized wikis)
+ *   - Our domain extensions: tech, finance, personal, openclaw, ops (domain-organized wikis)
  *   - Our entity prefix: entities (we kept some legacy entities/projects/ pages)
  */
-const DIR_PATTERN = '(?:people|companies|meetings|concepts|deal|civic|project|projects|source|media|yc|tech|finance|personal|openclaw|entities)';
+const DIR_PATTERN = '(?:people|companies|meetings|concepts|deal|civic|project|projects|source|media|yc|tech|finance|personal|openclaw|entities|ops)';
 
 /**
  * Match `[Name](path)` markdown links pointing to entity directories.
@@ -865,7 +865,16 @@ export function queryBasenameIndex(idx: Map<string, string[]>, name: string): st
   if (!name || typeof name !== 'string') return [];
   const trimmed = name.trim();
   if (!trimmed) return [];
-  const hit = idx.get(trimmed) ?? idx.get(trimmed.toLowerCase()) ?? idx.get(normalizeBasename(trimmed));
+  let hit = idx.get(trimmed) ?? idx.get(trimmed.toLowerCase()) ?? idx.get(normalizeBasename(trimmed));
+  // Issue #2576 bug 2: path-style refs (`runbooks/2026-05-01-x`) from dirs
+  // outside DIR_PATTERN reach here, but normalizeBasename strips slashes
+  // into a garbage key (`runbooks2026-05-01-x`) that can never hit the
+  // tail-keyed index. Fall back to the path tail so qualified refs resolve
+  // by basename like everything else.
+  if (!hit && trimmed.includes('/')) {
+    const tail = trimmed.slice(trimmed.lastIndexOf('/') + 1).trim();
+    if (tail) hit = idx.get(tail) ?? idx.get(tail.toLowerCase()) ?? idx.get(normalizeBasename(tail));
+  }
   return hit ? [...hit].sort(basenameSort) : [];
 }
 

test/backlinks.test.ts

@@ -4,7 +4,6 @@ import {
   extractPageTitle,
   hasBacklink,
   buildBacklinkEntry,
-  parseBacklinksArgs,
 } from '../src/commands/backlinks.ts';
 
 describe('extractEntityRefs', () => {
@@ -105,26 +104,3 @@ describe('findBacklinkGaps dedupe (v0.36.x #967 regression)', () => {
     }
   });
 });
-
-describe('parseBacklinksArgs', () => {
-  test('uses positional dir for check and fix subcommands', () => {
-    expect(parseBacklinksArgs(['check', '/tmp/brain']).brainDir).toBe('/tmp/brain');
-    expect(parseBacklinksArgs(['fix', '/tmp/brain']).brainDir).toBe('/tmp/brain');
-  });
-
-  test('defaults to cwd when no dir given', () => {
-    expect(parseBacklinksArgs(['check']).brainDir).toBe('.');
-  });
-
-  test('--dir overrides positional dir and preserves dry-run', () => {
-    const parsed = parseBacklinksArgs(['fix', '/tmp/ignored', '--dir', '/tmp/brain', '--dry-run']);
-    expect(parsed.subcommand).toBe('fix');
-    expect(parsed.brainDir).toBe('/tmp/brain');
-    expect(parsed.dryRun).toBe(true);
-  });
-
-  test('--dir missing its value falls back to positional dir', () => {
-    expect(parseBacklinksArgs(['check', '/tmp/brain', '--dir']).brainDir).toBe('/tmp/brain');
-    expect(parseBacklinksArgs(['check', '--dir', '--dry-run']).brainDir).toBe('.');
-  });
-});

test/extract-stale.test.ts

@@ -209,6 +209,24 @@ describe('gbrain extract --stale', () => {
     expect(usRows[0]?.eq).toBe(true);
   });
 
+  test('version-arm floor: page edited BEFORE LINK_EXTRACTOR_VERSION_TS clears after --stale (issue #2576 bug 3)', async () => {
+    // A page whose updated_at predates the version watermark used to be
+    // stamped at its updated_at (< versionTs), so the version arm re-fired
+    // every run — permanently stale. The sweep now floors the stamp at
+    // versionTs. (The #1768 test above also covers this since the v0.42.x
+    // VERSION_TS bump moved its date below the watermark, but this pins the
+    // behavior explicitly so a date "repair" there can't drop coverage.)
+    await engine.putPage('people/alice', personPage('Alice'));
+    await engine.executeRaw(`UPDATE pages SET updated_at = '2000-01-01T00:00:00Z' WHERE slug = 'people/alice'`);
+    expect(await engine.countStalePagesForExtraction({ versionTs: LINK_EXTRACTOR_VERSION_TS })).toBe(1);
+
+    await runExtract(engine, ['--stale']);
+    // Pre-floor this stayed 1 forever (stamp < versionTs → version arm re-fires).
+    expect(await engine.countStalePagesForExtraction({ versionTs: LINK_EXTRACTOR_VERSION_TS })).toBe(0);
+    await runExtract(engine, ['--stale']);
+    expect(await engine.countStalePagesForExtraction({ versionTs: LINK_EXTRACTOR_VERSION_TS })).toBe(0);
+  });
+
   test('CDX-4 (D2): a link-flush throw aborts the sweep and leaves pages UNSTAMPED', async () => {
     await engine.putPage('people/alice', personPage('Alice'));
     await engine.putPage('companies/acme', companyPage('Acme', '[Alice](people/alice) founded [Acme](companies/acme).'));

test/link-extraction.test.ts

@@ -140,6 +140,15 @@ describe('extractEntityRefs', () => {
     expect(wikiRefs[0].needsResolution).toBe(true);
   });
 
+  test('recognizes ops/ qualified wikilinks (issue #2576 bug 2)', () => {
+    // `ops` was missing from DIR_PATTERN, so [[ops/...]] fell through to
+    // the generic 2c pass (needsResolution) instead of being a real ref.
+    const refs = extractEntityRefs('Deployed via [[ops/services/pointer-agent]].');
+    expect(refs.length).toBe(1);
+    expect(refs[0].slug).toBe('ops/services/pointer-agent');
+    expect(refs[0].needsResolution).toBeUndefined();
+  });
+
   test('skips qualified-syntax tokens (those belong to 2a)', () => {
     // [[wiki:topics/ai]] looks like 2a's qualified shape — even though
     // it wouldn't satisfy DIR_PATTERN, 2c must not claim it either
@@ -1069,6 +1078,15 @@ describe('makeResolver — fallback chain', () => {
     ]);
   });
 
+  test('resolveBasenameMatches: path-style ref falls back to the tail (issue #2576 bug 2)', async () => {
+    // normalizeBasename strips slashes, so `runbooks/2026-05-01-pointer-agent`
+    // used to normalize to a garbage key that never hit the tail-keyed index.
+    const engine = makeFakeEngineWithSlugs(['ops/changes/2026-05-01-pointer-agent']);
+    const r = makeResolver(engine);
+    expect(await r.resolveBasenameMatches!('runbooks/2026-05-01-pointer-agent'))
+      .toEqual(['ops/changes/2026-05-01-pointer-agent']);
+  });
+
   test('resolveBasenameMatches: case-insensitive fallback', async () => {
     const engine = makeFakeEngineWithSlugs(['companies/fast-weigh']);
     const r = makeResolver(engine);