@3fn/core 13.0.0 → 14.0.0

package/mcp-server/src/index.ts

@@ -346,7 +346,15 @@ class MCPDocumentationServer {
   }
 
   /**
-   * Set up graceful shutdown handlers
+   * Set up graceful shutdown handlers.
+   *
+   * stdin EOF ('end'/'close') is a first-class shutdown trigger: a stdio MCP server
+   * whose parent client died (or gracefully closed the pipe) has no one to serve, but
+   * the file watcher keeps the event loop alive forever — found live at Spec 122 U3
+   * (~230 orphaned servers accumulated across harness runs, wedging later boots).
+   * Self-exiting on EOF also makes graceful client closes immediate: the MCP SDK's
+   * StdioClientTransport.close() ends stdin and waits up to 2s for exactly this exit
+   * before escalating to SIGTERM.
    */
   private setupShutdownHandlers(): void {
     const shutdown = async () => {
@@ -356,6 +364,8 @@ class MCPDocumentationServer {
 
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
+    process.stdin.on('end', shutdown);
+    process.stdin.on('close', shutdown);
   }
 }
 
@@ -417,11 +427,19 @@ async function main(): Promise<void> {
   await server.start();
 }
 
-// Run the server
-main().catch((error) => {
-  console.error('[MCP Server] Fatal error:', error);
-  process.exit(1);
-});
+// Run the server ONLY when this module is the process entry point (executed
+// directly — `node mcp-server/dist/index.js`, or the esbuild `dist/mcp/docs-mcp.js`
+// bundle a consumer launches). Importing this module as a LIBRARY (Spec 122 imports
+// the re-exported WORKFLOW_RULES from the package entry) must NOT start the server;
+// the previous unconditional call started an MCP server as an import side effect.
+// This module is CommonJS (tsconfig `module: commonjs`), so `require.main === module`
+// is the correct entry check — verified to still fire under the esbuild CJS bundle.
+if (require.main === module) {
+  main().catch((error) => {
+    console.error('[MCP Server] Fatal error:', error);
+    process.exit(1);
+  });
+}
 
 // Export for testing
 export { MCPDocumentationServer };

package/mcp-server/src/indexer/DocumentIndexer.ts

@@ -4,7 +4,7 @@ import { extractMetadata } from './metadata-parser';
 import { extractFrontmatterInfo } from './frontmatter-parser';
 import { extractHeadingStructure } from './heading-parser';
 import { resolveSection, SectionLookup } from './section-parser';
-import { extractCrossReferences } from './cross-ref-parser';
+import { extractCrossReferences, CrossReference as ParsedCrossReference } from './cross-ref-parser';
 import { estimateTokenCount } from '../utils/token-estimator';
 import { determineIndexHealth } from './index-health';
 import { seedLegacyPathsFromFrozenManifest } from '../legacy-path';
@@ -65,6 +65,25 @@ export class DocumentIndexer {
   private idIndex: Map<string, string> = new Map();          // id → indexedKey
   private legacyPathIndex: Map<string, string> = new Map();  // normalizedLegacyPath → indexedKey
 
+  /**
+   * Validated cross-references per indexed key (Spec 119-B OB-1, Decision 1:
+   * extract-then-validate at INDEX time, one validation point). indexFile
+   * stores the raw parser output (bare-id candidates still tagged); the
+   * post-index validation pass (or reindexFile's inline pass) replaces it with
+   * the validated, TAG-STRIPPED set — the candidate tag never escapes the
+   * indexer. All read surfaces (list_cross_references, getDocumentSummary,
+   * index-health metrics) consume THIS map, never re-extract, so the
+   * crossReferences count is a stable index property.
+   */
+  private crossRefsByKey: Map<string, ParsedCrossReference[]> = new Map();
+  /**
+   * Bare-id candidates dropped by validation (target not in idIndex) — the
+   * typo-suspicious class. Surfaced on two channels (design Component 6):
+   * scan-cross-references.sh lists individually; index-health emits ONE
+   * aggregate warning when count > 0.
+   */
+  private droppedIdCandidates: Array<{ sourceKey: string; target: string; section: string; lineNumber: number }> = [];
+
   private lastIndexTime: string | undefined;
   private directoryPath: string | undefined;
   private logsDirectory: string;
@@ -104,6 +123,8 @@ export class DocumentIndexer {
     this.documentContent.clear();
     this.idIndex.clear();
     this.legacyPathIndex.clear();
+    this.crossRefsByKey.clear();
+    this.droppedIdCandidates = [];
     // RE-SEED OBLIGATION (Task 3.2): legacyPathIndex is seeded out-of-band from a
     // build-time manifest via loadLegacyPathManifest — it is NOT derived from
     // on-disk scanning (the original `.kiro/steering/…` paths no longer exist
@@ -131,6 +152,13 @@ export class DocumentIndexer {
     // no legacy fallback (correct degraded behavior).
     this.seedLegacyPaths();
 
+    // CROSS-REF VALIDATION PASS (Spec 119-B OB-1): joins the same post-index
+    // hook as the legacy re-seed — idIndex is complete here, so every bare-id
+    // candidate can be validated in ONE place (Decision 1: index-time, never
+    // query-time). Hits become real cross-references (target already the doc
+    // id); misses are dropped and recorded for the two surfacing channels.
+    this.validateAllCrossReferences();
+
     // Update last index time
     this.lastIndexTime = new Date().toISOString();
 
@@ -157,12 +185,20 @@ export class DocumentIndexer {
       this.pruneAddressingEntriesForKey(filePath);
       this.documentMap.delete(filePath);
       this.documentContent.delete(filePath);
+      this.crossRefsByKey.delete(filePath);
+      this.droppedIdCandidates = this.droppedIdCandidates.filter(d => d.sourceKey !== filePath);
       this.lastIndexTime = new Date().toISOString();
       return;
     }
 
     // Re-index the file (the re-add branch repopulates idIndex via indexFile).
     await this.indexFile(filePath);
+    // Inline cross-ref validation against the STANDING idIndex (Spec 119-B
+    // OB-1) — same validation function as the full-rebuild pass. ACCEPTED EDGE
+    // (pinned by test): a ref to a NEW doc B not yet in the standing idIndex is
+    // dropped until the next full rebuild — covered operationally by the
+    // write-side rebuild protocol.
+    this.validateCrossReferencesForKey(filePath);
     this.lastIndexTime = new Date().toISOString();
   }
 
@@ -206,14 +242,16 @@ export class DocumentIndexer {
    * @param filePath - Path to document
    */
   getDocumentSummary(filePath: string): DocumentSummary {
-    const content = this.getDocumentContent(filePath);
+    const { indexedKey } = this.resolveRef(filePath);
+    const content = this.documentContent.get(indexedKey)!;
     const metadata = extractMetadata(content);
 
     // Extract heading structure
     const outline = extractHeadingStructure(content);
 
-    // Extract cross-references
-    const crossReferences = extractCrossReferences(content, filePath);
+    // Cross-references: the VALIDATED index-time set (Spec 119-B OB-1) — same
+    // single source list_cross_references serves; dropped candidates excluded.
+    const crossReferences = this.crossRefsByKey.get(indexedKey) ?? [];
 
     // Convert CrossReference[] to CrossReferenceInfo[]
     const crossReferenceInfo = crossReferences.map(ref => ({
@@ -350,12 +388,71 @@ export class DocumentIndexer {
   /**
    * List cross-references in a document
    * Returns links without following them
-   * 
-   * @param filePath - Path to document
+   *
+   * Spec 119-B OB-1: the incoming ref routes through the SAME resolver chain
+   * as every other document-addressed tool (id → indexed key → legacy path,
+   * D5), and the result is the VALIDATED index-time set — `.md` path refs
+   * unchanged, bare-id refs enumerated with target = the doc id; dropped
+   * candidates never appear. Public shape unchanged (no kind tag).
+   *
+   * @param filePath - Document ref: id, indexed relative path, or legacy path
    */
   listCrossReferences(filePath: string): CrossReference[] {
-    const content = this.getDocumentContent(filePath);
-    return extractCrossReferences(content, filePath);
+    const { indexedKey } = this.resolveRef(filePath);
+    return this.crossRefsByKey.get(indexedKey) ?? [];
+  }
+
+  /**
+   * Bare-id candidates dropped by validation (Spec 119-B OB-1) — the
+   * typo-suspicious class surfaced via index-health's aggregate warning and
+   * scan-cross-references.sh's individual listing.
+   */
+  getDroppedIdCandidates(): ReadonlyArray<{ sourceKey: string; target: string; section: string; lineNumber: number }> {
+    return this.droppedIdCandidates;
+  }
+
+  /**
+   * Validate ALL stored cross-reference sets against the completed idIndex
+   * (the post-index hook — Spec 119-B OB-1, Decision 1's single validation
+   * point). Resets the dropped-candidate record.
+   */
+  private validateAllCrossReferences(): void {
+    this.droppedIdCandidates = [];
+    for (const key of this.crossRefsByKey.keys()) {
+      this.validateCrossReferencesForKey(key);
+    }
+  }
+
+  /**
+   * Validate one document's stored cross-references against the CURRENT
+   * idIndex. `.md` path refs pass through untouched; bare-id candidates are
+   * kept iff their target is a known doc id (tag stripped — it never escapes
+   * the indexer) and dropped-with-record otherwise.
+   */
+  private validateCrossReferencesForKey(key: string): void {
+    const raw = this.crossRefsByKey.get(key);
+    if (!raw) return;
+
+    // Replace any prior dropped entries for this key (reindex path).
+    this.droppedIdCandidates = this.droppedIdCandidates.filter(d => d.sourceKey !== key);
+
+    const validated: ParsedCrossReference[] = [];
+    for (const ref of raw) {
+      if (ref.kind !== 'id-candidate') {
+        validated.push(ref);
+      } else if (this.idIndex.has(ref.target)) {
+        const { kind: _kind, ...publicRef } = ref;
+        validated.push(publicRef);
+      } else {
+        this.droppedIdCandidates.push({
+          sourceKey: key,
+          target: ref.target,
+          section: ref.section,
+          lineNumber: ref.lineNumber,
+        });
+      }
+    }
+    this.crossRefsByKey.set(key, validated);
   }
 
   /**
@@ -483,6 +580,13 @@ export class DocumentIndexer {
 
     this.documentMap.set(filePath, documentMetadata);
 
+    // Store the RAW parser output (bare-id candidates still tagged) for the
+    // post-index validation pass (Spec 119-B OB-1). Mid-indexing this map may
+    // hold unvalidated candidates — accepted and explicit (design Component 6):
+    // no consumer reads cross-refs during indexing; indexing is atomic from the
+    // API's view.
+    this.crossRefsByKey.set(filePath, extractCrossReferences(content, filePath));
+
     // Build the id index (id → indexed key). First drop any PRIOR id forward-entry
     // that still points at this same key — covers an in-place id rewrite (reindexFile
     // re-add branch with NO delete event), which would otherwise leave a stale
@@ -690,10 +794,16 @@ export class DocumentIndexer {
     }
 
     // Use determineIndexHealth for comprehensive health check
+    let validatedCount = 0;
+    for (const refs of this.crossRefsByKey.values()) validatedCount += refs.length;
     const health = determineIndexHealth({
       indexedDocuments: this.documentContent,
       directoryPath: this.directoryPath,
-      lastIndexTime: this.lastIndexTime
+      lastIndexTime: this.lastIndexTime,
+      crossRefTotals: {
+        validatedCount,
+        droppedBareIdCount: this.droppedIdCandidates.length
+      }
     });
 
     this.logIndexStateChange('validation_completed', { 

package/mcp-server/src/indexer/__tests__/bare-id-crossrefs.test.ts

@@ -0,0 +1,250 @@
+/**
+ * Bare-id cross-reference enumeration — unit tests (Spec 119-B OB-1, R9,
+ * design Component 6).
+ *
+ * Covers: the parser's bare-id candidate grammar (positives + false-positive
+ * guards), `.md` extraction unchanged (no tag on path refs), the indexer's
+ * post-index validation pass (hits kept tag-stripped, misses dropped with
+ * record), the migrated-doc enumeration case (token-governance-pattern
+ * fixture), the reindexFile ACCEPTED EDGE (new-doc ref dropped until full
+ * rebuild), the D5 addressing contract on listCrossReferences, and the
+ * index-health aggregate warning + stable validated count.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { extractCrossReferences, BARE_ID_GRAMMAR } from '../cross-ref-parser';
+import { DocumentIndexer } from '../DocumentIndexer';
+
+const TEST_FIXTURES_DIR = path.join(__dirname, 'fixtures');
+
+function docWithId(id: string, h1: string, body: string): string {
+  return `---
+name: ${h1}
+id: ${id}
+description: fixture doc
+---
+
+# ${h1}
+
+**Date**: 2026-08-02
+**Purpose**: OB-1 fixture
+**Organization**: test-org
+**Scope**: test
+**Layer**: 2
+**Relevant Tasks**: testing
+**Last Reviewed**: 2026-08-02
+
+## Body
+
+${body}
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Parser: grammar + guards (7.2)
+// ---------------------------------------------------------------------------
+
+describe('cross-ref parser — bare-id candidate extraction (Spec 119-B OB-1)', () => {
+  it('grammar positives: extracts bare-id candidates with the internal tag', () => {
+    const content = '## S\n\nsee [Token Governance](token-governance) and [x](a1) and [y](x-y-z2).';
+    const refs = extractCrossReferences(content, 'test.md');
+    expect(refs).toHaveLength(3);
+    expect(refs.map(r => r.target)).toEqual(['token-governance', 'a1', 'x-y-z2']);
+    for (const r of refs) expect(r.kind).toBe('id-candidate');
+  });
+
+  it('false-positive guards: anchors, URLs, paths, dotted names, uppercase, underscores, code-ish targets are NOT candidates', () => {
+    const content = [
+      '## S',
+      '[anchor](#section)',
+      '[url](https://example.com/page)',
+      '[url2](mailto:x@y.z)',
+      '[relpath](./sub/thing)',
+      '[abspath](/root/thing)',
+      '[dotted](file.txt)',
+      '[upper](Not-An-Id)',
+      '[underscore](not_an_id)',
+      '[hyphen-start](-bad)',
+      '[empty]()',
+    ].join('\n');
+    const refs = extractCrossReferences(content, 'test.md');
+    expect(refs).toHaveLength(0);
+  });
+
+  it('.md extraction is unchanged: path refs carry NO kind tag and keep their exact shape', () => {
+    const content = '## Section One\n\nsee [Guide](./guide.md) and [Other](docs/other.md#anchor).';
+    const refs = extractCrossReferences(content, 'test.md');
+    expect(refs).toEqual([
+      { target: './guide.md', context: 'Guide', section: 'Section One', lineNumber: 3 },
+      { target: 'docs/other.md#anchor', context: 'Other', section: 'Section One', lineNumber: 3 },
+    ]);
+  });
+
+  it('mixed line: .md ref and bare-id candidate extracted side by side', () => {
+    const content = '## S\n\n[A](a.md) then [B](token-governance) then [C](#x).';
+    const refs = extractCrossReferences(content, 'test.md');
+    expect(refs.map(r => [r.target, r.kind ?? 'path'])).toEqual([
+      ['a.md', 'path'],
+      ['token-governance', 'id-candidate'],
+    ]);
+  });
+
+  it('grammar constant rejects / . : # by construction', () => {
+    for (const bad of ['a/b', 'a.b', 'a:b', 'a#b', 'A', '-a', '']) {
+      expect(BARE_ID_GRAMMAR.test(bad) && !/[/.:#]/.test(bad)).toBe(false);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Indexer: validation pass + surfacing + D5 (7.3 / 7.4)
+// ---------------------------------------------------------------------------
+
+describe('DocumentIndexer — bare-id validation on the post-index hook (Spec 119-B OB-1)', () => {
+  let indexer: DocumentIndexer;
+  let testDir: string;
+
+  beforeEach(() => {
+    indexer = new DocumentIndexer();
+    testDir = path.join(TEST_FIXTURES_DIR, `bareid-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fs.mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('validates candidates against idIndex: hits kept (tag stripped), misses dropped with record', async () => {
+    fs.writeFileSync(
+      path.join(testDir, 'doc-a.md'),
+      docWithId('doc-a', 'Doc A', 'see [B](doc-b), [bogus](no-such-id), and [file](other.md).')
+    );
+    fs.writeFileSync(path.join(testDir, 'doc-b.md'), docWithId('doc-b', 'Doc B', 'plain body.'));
+    await indexer.indexDirectory(testDir);
+
+    const refs = indexer.listCrossReferences('doc-a');
+    expect(refs.map(r => r.target).sort()).toEqual(['doc-b', 'other.md']);
+    // The candidate tag never escapes the indexer (public shape unchanged)
+    for (const r of refs) expect('kind' in r).toBe(false);
+
+    const dropped = indexer.getDroppedIdCandidates();
+    expect(dropped).toHaveLength(1);
+    expect(dropped[0].target).toBe('no-such-id');
+    expect(dropped[0].sourceKey).toContain('doc-a.md');
+    expect(dropped[0].lineNumber).toBeGreaterThan(0);
+  });
+
+  it('migrated-doc enumeration: a token-governance-pattern doc has its bare-id refs enumerated', async () => {
+    // Mirrors the real post-U3 pattern: prose linking sibling docs by bare id
+    const body = [
+      'Token selection: see [Token Quick Reference](token-quick-reference) for patterns,',
+      '[Rosetta System Architecture](rosetta-system-architecture) for the pipeline,',
+      'and the [DTCG guide](dtcg-integration-guide) for exports.',
+    ].join('\n');
+    fs.writeFileSync(path.join(testDir, 'token-governance.md'), docWithId('token-governance', 'Token Governance', body));
+    fs.writeFileSync(path.join(testDir, 'tqr.md'), docWithId('token-quick-reference', 'Token Quick Reference', 'x'));
+    fs.writeFileSync(path.join(testDir, 'rsa.md'), docWithId('rosetta-system-architecture', 'Rosetta System Architecture', 'x'));
+    fs.writeFileSync(path.join(testDir, 'dtcg.md'), docWithId('dtcg-integration-guide', 'DTCG Integration Guide', 'x'));
+    await indexer.indexDirectory(testDir);
+
+    const refs = indexer.listCrossReferences('token-governance');
+    expect(refs.map(r => r.target).sort()).toEqual([
+      'dtcg-integration-guide',
+      'rosetta-system-architecture',
+      'token-quick-reference',
+    ]);
+    expect(indexer.getDroppedIdCandidates()).toHaveLength(0);
+    // Context + section + line survive for bare-id refs (same fields as .md refs)
+    expect(refs[0].section).toBe('Body');
+    expect(refs[0].context.length).toBeGreaterThan(0);
+  });
+
+  it('ACCEPTED EDGE (pinned): reindexFile drops a ref to a NEW doc not yet in the standing idIndex; the next full rebuild restores it', async () => {
+    const aPath = path.join(testDir, 'doc-a.md');
+    fs.writeFileSync(aPath, docWithId('doc-a', 'Doc A', 'no links yet.'));
+    await indexer.indexDirectory(testDir);
+
+    // NEW doc B lands on disk; doc A is edited to reference it; ONLY A is reindexed.
+    fs.writeFileSync(path.join(testDir, 'doc-b.md'), docWithId('doc-b', 'Doc B', 'new doc.'));
+    fs.writeFileSync(aPath, docWithId('doc-a', 'Doc A', 'now see [B](doc-b).'));
+    await indexer.reindexFile(aPath);
+
+    // B is not in the standing idIndex (it was never indexed) → ref dropped
+    expect(indexer.listCrossReferences('doc-a').map(r => r.target)).toEqual([]);
+    expect(indexer.getDroppedIdCandidates().map(d => d.target)).toEqual(['doc-b']);
+
+    // Full rebuild: idIndex complete → the ref validates
+    await indexer.indexDirectory(testDir);
+    expect(indexer.listCrossReferences('doc-a').map(r => r.target)).toEqual(['doc-b']);
+    expect(indexer.getDroppedIdCandidates()).toHaveLength(0);
+  });
+
+  it('reindexFile validates inline when the target IS in the standing idIndex', async () => {
+    const aPath = path.join(testDir, 'doc-a.md');
+    fs.writeFileSync(aPath, docWithId('doc-a', 'Doc A', 'no links yet.'));
+    fs.writeFileSync(path.join(testDir, 'doc-b.md'), docWithId('doc-b', 'Doc B', 'x'));
+    await indexer.indexDirectory(testDir);
+
+    fs.writeFileSync(aPath, docWithId('doc-a', 'Doc A', 'now see [B](doc-b).'));
+    await indexer.reindexFile(aPath);
+    expect(indexer.listCrossReferences('doc-a').map(r => r.target)).toEqual(['doc-b']);
+  });
+
+  it('D5: listCrossReferences resolves via id, indexed key, and ./-prefixed key through the shared resolver chain', async () => {
+    const aPath = path.join(testDir, 'doc-a.md');
+    fs.writeFileSync(aPath, docWithId('doc-a', 'Doc A', 'see [B](doc-b) and [G](./guide.md).'));
+    fs.writeFileSync(path.join(testDir, 'doc-b.md'), docWithId('doc-b', 'Doc B', 'x'));
+    await indexer.indexDirectory(testDir);
+
+    const byId = indexer.listCrossReferences('doc-a');
+    const byKey = indexer.listCrossReferences(aPath);
+    const byDotSlash = indexer.listCrossReferences(`./${aPath}`);
+    expect(byKey).toEqual(byId);
+    expect(byDotSlash).toEqual(byId);
+    expect(byId.map(r => r.target).sort()).toEqual(['./guide.md', 'doc-b']);
+  });
+
+  it('D5 miss: an unresolvable ref throws DocumentNotResolved (same contract as the other document tools)', async () => {
+    fs.writeFileSync(path.join(testDir, 'doc-a.md'), docWithId('doc-a', 'Doc A', 'x'));
+    await indexer.indexDirectory(testDir);
+    expect(() => indexer.listCrossReferences('nope-never')).toThrow(/Document not found/);
+  });
+
+  it('getDocumentSummary serves the same validated set (dropped candidates never appear)', async () => {
+    fs.writeFileSync(
+      path.join(testDir, 'doc-a.md'),
+      docWithId('doc-a', 'Doc A', 'see [B](doc-b) and [bogus](no-such-id).')
+    );
+    fs.writeFileSync(path.join(testDir, 'doc-b.md'), docWithId('doc-b', 'Doc B', 'x'));
+    await indexer.indexDirectory(testDir);
+
+    const summary = indexer.getDocumentSummary('doc-a');
+    expect(summary.crossReferences.map(r => r.target)).toEqual(['doc-b']);
+  });
+
+  it('index-health: totalCrossReferences is the validated count and drops emit ONE aggregate warning', async () => {
+    fs.writeFileSync(
+      path.join(testDir, 'doc-a.md'),
+      docWithId('doc-a', 'Doc A', 'see [B](doc-b), [bogus](no-such-id), and [file](guide.md).')
+    );
+    fs.writeFileSync(path.join(testDir, 'doc-b.md'), docWithId('doc-b', 'Doc B', 'x'));
+    await indexer.indexDirectory(testDir);
+
+    const health = indexer.getIndexHealth();
+    // validated = doc-b (bare-id hit) + guide.md (path ref) = 2; bogus dropped
+    expect(health.metrics.totalCrossReferences).toBe(2);
+    const warning = health.warnings.filter(w => w.includes('unresolved bare-id'));
+    expect(warning).toHaveLength(1);
+    expect(warning[0]).toBe('1 unresolved bare-id link targets — run scan-cross-references.sh for the list');
+  });
+
+  it('index-health: zero drops emits NO bare-id warning', async () => {
+    fs.writeFileSync(path.join(testDir, 'doc-a.md'), docWithId('doc-a', 'Doc A', 'see [B](doc-b).'));
+    fs.writeFileSync(path.join(testDir, 'doc-b.md'), docWithId('doc-b', 'Doc B', 'x'));
+    await indexer.indexDirectory(testDir);
+
+    const health = indexer.getIndexHealth();
+    expect(health.warnings.filter(w => w.includes('unresolved bare-id'))).toHaveLength(0);
+  });
+});

package/mcp-server/src/indexer/cross-ref-parser.ts

@@ -8,12 +8,28 @@
  */
 
 export interface CrossReference {
-  target: string;                  // Referenced document path
+  target: string;                  // Referenced document path (or doc id, for bare-id refs)
   context: string;                 // Context description from link text
   section: string;                 // Source section containing reference
   lineNumber: number;              // Line number in source file
+  /**
+   * INTERNAL-ONLY candidate tag (Spec 119-B OB-1). Present ONLY on bare-id
+   * candidates awaiting idIndex validation; `.md` path refs never carry it
+   * (their extracted shape is unchanged). The tag never escapes the indexer:
+   * validation strips it before refs reach any public surface.
+   */
+  kind?: 'id-candidate';
 }
 
+/**
+ * Bare-id candidate grammar (Spec 119-B OB-1 / design Component 6): a link
+ * target is an id candidate IF it matches this AND contains none of `/ . : #`
+ * (the character class already excludes them; the explicit guard in the
+ * extractor documents the contract). Validation against idIndex happens in the
+ * indexer's post-index pass — the parser stays a dumb extractor.
+ */
+export const BARE_ID_GRAMMAR = /^[a-z0-9][a-z0-9-]*$/;
+
 /**
  * Extract cross-references from markdown content
  * 
@@ -57,6 +73,18 @@ export function extractCrossReferences(content: string, _filePath: string): Cros
           section: currentSection,
           lineNumber: i + 1
         });
+      } else if (BARE_ID_GRAMMAR.test(target) && !/[/.:#]/.test(target)) {
+        // Bare-id candidate (Spec 119-B OB-1): tagged, NOT validated here —
+        // anchors (#…), URLs (contain :/), and paths (contain / or .) never
+        // reach this branch. The indexer's post-index pass validates against
+        // idIndex and drops misses.
+        references.push({
+          target,
+          context,
+          section: currentSection,
+          lineNumber: i + 1,
+          kind: 'id-candidate'
+        });
       }
     }
   }

package/mcp-server/src/indexer/index-health.ts

@@ -24,6 +24,17 @@ export interface HealthCheckOptions {
   directoryPath: string;
   /** Last index time (ISO string) */
   lastIndexTime?: string;
+  /**
+   * Validated cross-reference totals from the indexer (Spec 119-B OB-1).
+   * When provided, `totalCrossReferences` reports the VALIDATED index-time
+   * count (a stable index property — Decision 1) instead of a re-extraction,
+   * and `droppedBareIdCount > 0` emits ONE aggregate warning pointing at
+   * scan-cross-references.sh for the individual listing.
+   */
+  crossRefTotals?: {
+    validatedCount: number;
+    droppedBareIdCount: number;
+  };
 }
 
 /**
@@ -38,7 +49,7 @@ export interface HealthCheckOptions {
  * @returns IndexHealth with status, errors, warnings, and metrics
  */
 export function determineIndexHealth(options: HealthCheckOptions): IndexHealth {
-  const { indexedDocuments, directoryPath, lastIndexTime } = options;
+  const { indexedDocuments, directoryPath, lastIndexTime, crossRefTotals } = options;
   
   const errors: string[] = [];
   const warnings: string[] = [];
@@ -68,9 +79,23 @@ export function determineIndexHealth(options: HealthCheckOptions): IndexHealth {
     warnings.push(`Malformed metadata: ${malformedDocs.join(', ')}`);
   }
   
+  // Dropped bare-id candidates: ONE aggregate warning on the daily-consumer
+  // channel (Spec 119-B OB-1, design Component 6) — per-item detail lives in
+  // the scanner, not here.
+  if (crossRefTotals && crossRefTotals.droppedBareIdCount > 0) {
+    warnings.push(
+      `${crossRefTotals.droppedBareIdCount} unresolved bare-id link targets — run scan-cross-references.sh for the list`
+    );
+  }
+
   // Calculate metrics
   const metrics = calculateIndexMetrics(indexedDocuments);
-  
+  // Spec 119-B OB-1: prefer the indexer's validated count (stable index
+  // property) over re-extraction when supplied.
+  if (crossRefTotals) {
+    metrics.totalCrossReferences = crossRefTotals.validatedCount;
+  }
+
   // Determine status
   let status: IndexHealthStatus;
   if (errors.length > 0) {