@smartmemory/compose 0.1.38-beta → 0.1.40-beta

package/lib/feature-validator.js

@@ -13,7 +13,19 @@
  *
  * Each finding: { severity: 'error'|'warning'|'info', kind, feature_code?, detail, source? }.
  *
- * Catalog (27 kinds): see docs/features/COMP-MCP-VALIDATE/design.md.
+ * Catalog (32 kinds). The original 27 cross-artifact kinds, plus the 5
+ * COMP-MCP-XREF-VALIDATE (#16) read-only external-reference kinds:
+ *   - XREF_DRIFT            (warning) resolved state blatantly contradicts the
+ *                                     citing row / explicit expect=
+ *   - XREF_TARGET_MISSING   (error)   github 404 / local target absent
+ *   - XREF_MALFORMED        (warning) <!--xref:…--> matched but failed grammar
+ *   - XREF_RESOLUTION_SKIPPED (warning) offline / no-token / rate-limit / ≥500
+ *                                     / gate off — NEVER error, never aborts
+ *   - XREF_URL_UNCHECKED    (info)    url + reserved url-class providers
+ *                                     (jira|linear|notion|obsidian) — recorded,
+ *                                     not resolved
+ * Full catalog + trigger/degrade/gating contract:
+ *   docs/features/COMP-MCP-VALIDATE/design.md
  */
 
 import fs from 'node:fs';
@@ -22,6 +34,8 @@ import { fileURLToPath } from 'node:url';
 import { FEATURE_CODE_RE_STRICT, validateCode } from './feature-code.js';
 import { parseRoadmap } from './roadmap-parser.js';
 import { listFeatures, readFeature } from './feature-json.js';
+import { parseCitations } from './xref-citation.js';
+import { GitHubApi } from './tracker/github-api.js';
 import { ArtifactManager } from '../server/artifact-manager.js';
 import { SchemaValidator } from '../server/schema-validator.js';
 
@@ -79,6 +93,11 @@ function loadValidationContext(cwd, options = {}) {
   // status values (PARTIAL, COMPLETE) match the strict code regex, or where
   // descriptions contain code-like uppercase tokens.
   let roadmapRows = [];
+  // COMP-MCP-XREF-VALIDATE #16: anon-row-safe citation capture. Independent
+  // of roadmapByCode (which drops rows whose code is not strict). Additive —
+  // does not change roadmapRows / position / roadmapByCode.
+  const citationRows = [];
+  let citePosition = 0;
   try {
     const text = fs.readFileSync(options.roadmapPath || paths.roadmap, 'utf8');
     let phaseId = '';
@@ -123,9 +142,18 @@ function loadValidationContext(cwd, options = {}) {
       if (codeIdx >= cols.length || statusIdx >= cols.length) continue;
 
       const codeRaw = cols[codeIdx].replace(/\*/g, '').replace(/`/g, '').trim();
-      if (!FEATURE_CODE_RE_STRICT.test(codeRaw)) continue;
-      const status = cols[statusIdx].replace(/\*/g, '').trim();
       const description = descIdx >= 0 && descIdx < cols.length ? cols[descIdx] : '';
+      const status = cols[statusIdx].replace(/\*/g, '').trim();
+      const isStrictCode = FEATURE_CODE_RE_STRICT.test(codeRaw);
+      // Anon-inclusive citation row capture (independent counter).
+      citePosition += 1;
+      citationRows.push({
+        code: isStrictCode ? codeRaw : null,
+        description,
+        status,
+        rowPosition: citePosition,
+      });
+      if (!isStrictCode) continue;
       position += 1;
       roadmapRows.push({ code: codeRaw, description, status, phaseId, position });
     }
@@ -177,6 +205,7 @@ function loadValidationContext(cwd, options = {}) {
     visionItems,
     visionStateRaw,
     foldersByCode,
+    citationRows,
     externalPrefixes: options.externalPrefixes || [],
     featureJsonMode: options.featureJsonMode !== false,
   };
@@ -605,6 +634,335 @@ export async function validateFeature(cwd, code, options = {}) {
   return { scope: 'feature', feature_code: code, validated_at: nowIso(), findings };
 }
 
+// ---------------------------------------------------------------------------
+// COMP-MCP-XREF-VALIDATE #16 — read-only external-reference staleness checks
+// ---------------------------------------------------------------------------
+
+const WS_ID_RE = /^[a-z][a-z0-9-]{1,63}$/;
+const URL_CLASS = new Set(['url', 'jira', 'linear', 'notion', 'obsidian']);
+const TERMINAL_ISH = new Set(['COMPLETE', 'SUPERSEDED']);
+const OPEN_ISH = new Set(['PLANNED', 'IN_PROGRESS']);
+
+function resolveCitingWorkspaceId(cwd, options, cfg) {
+  if (options.citingWorkspaceId) return options.citingWorkspaceId;
+  if (cfg && typeof cfg.workspaceId === 'string' && WS_ID_RE.test(cfg.workspaceId)) {
+    return cfg.workspaceId;
+  }
+  const base = path.basename(cwd);
+  return base === 'forge' ? 'forge-top' : base;
+}
+
+function xrefGateOn(options, cfg) {
+  return options.external === true
+    || process.env.COMPOSE_XREF_ONLINE === '1'
+    || !!(cfg && cfg.xref && cfg.xref.prePushOnline === true);
+}
+
+// Build the normalized ExternalRef list from both carriers (roadmap citations
+// — anon-row-safe — and feature.json links[] kind:"external"). Parse errors
+// from the grammar become XREF_MALFORMED findings.
+function collectExternalRefs(ctx, citingWorkspaceId, findings) {
+  const refs = [];
+  for (const row of ctx.citationRows || []) {
+    const { refs: parsed, errors } = parseCitations(row.description || '');
+    for (const e of errors) {
+      findings.push(finding(
+        'warning', 'XREF_MALFORMED', row.code || undefined,
+        `row #${row.rowPosition}: malformed xref citation (${e.reason}) — "${String(row.description).slice(0, 80)}"`,
+        'roadmap-citation',
+      ));
+    }
+    for (const p of parsed) {
+      refs.push({
+        source: 'roadmap-citation',
+        citing: {
+          workspaceId: citingWorkspaceId,
+          code: row.code || null,
+          rowPosition: row.rowPosition,
+          rowDescription: String(row.description || '').slice(0, 80),
+          status: row.status || null,
+        },
+        provider: p.provider, repo: p.repo, issue: p.issue,
+        toCode: p.toCode, url: p.url, expect: p.expect, note: p.note,
+      });
+    }
+  }
+  for (const [code, folder] of ctx.foldersByCode) {
+    if (!folder.hasFeatureJson) continue;
+    let fj;
+    try { fj = JSON.parse(fs.readFileSync(path.join(folder.dir, 'feature.json'), 'utf8')); }
+    catch { continue; }
+    if (!Array.isArray(fj.links)) continue;
+    for (const l of fj.links) {
+      if (l && l.kind === 'external') {
+        refs.push({
+          source: 'feature-json-link',
+          citing: {
+            workspaceId: citingWorkspaceId,
+            code,
+            rowPosition: null,
+            rowDescription: null,
+            status: fj.status || ctx.roadmapByCode.get(code)?.status || null,
+          },
+          provider: l.provider, repo: l.repo ?? null, issue: l.issue ?? null,
+          toCode: l.to_code ?? null, url: l.url ?? null,
+          expect: l.expect ?? null, note: l.note ?? null,
+        });
+      }
+    }
+  }
+  return refs;
+}
+
+function locatorDetail(ref, msg) {
+  // citing.workspaceId is the spec-contracted "citing label" (spec §3.3/§4):
+  // surface it so cross-repo findings name which workspace cited the ref.
+  const ws = ref.citing.workspaceId ? `[${ref.citing.workspaceId}] ` : '';
+  if (ref.citing.code) return `${ws}${msg}`;
+  return `${ws}row #${ref.citing.rowPosition}: "${ref.citing.rowDescription}" — ${msg}`;
+}
+
+function githubDrift(ref, state) {
+  // explicit expect is authoritative
+  if (ref.expect === 'open' || ref.expect === 'closed') {
+    return state !== ref.expect
+      ? `expected ${ref.repo}#${ref.issue} to be ${ref.expect} but it is ${state}`
+      : null;
+  }
+  // absent expect → derive from citing-row status; blatant contradiction only
+  const s = ref.citing.status;
+  if (TERMINAL_ISH.has(s) && state === 'open') {
+    return `citing row is ${s} but ${ref.repo}#${ref.issue} is still open`;
+  }
+  if (OPEN_ISH.has(s) && state === 'closed') {
+    return `citing row is ${s} but ${ref.repo}#${ref.issue} is already closed`;
+  }
+  return null;
+}
+
+async function resolveGithubRef(ref, gh, findings) {
+  const code = ref.citing.code || undefined;
+  let r;
+  try {
+    r = await gh.getIssueResult(ref.issue);
+  } catch (e) {
+    if (e && e.rateLimit) { const x = new Error('ratelimit'); x._rateLimit = true; throw x; }
+    // offline / fetch reject / unexpected — per-ref degrade
+    findings.push(finding(
+      'warning', 'XREF_RESOLUTION_SKIPPED', code,
+      locatorDetail(ref, `github resolution skipped for ${ref.repo}#${ref.issue}: ${e && e.message ? e.message : e}`),
+      ref.source,
+    ));
+    return;
+  }
+  if (r.status === 404) {
+    findings.push(finding(
+      'error', 'XREF_TARGET_MISSING', code,
+      locatorDetail(ref, `github ${ref.repo}#${ref.issue} not found (404)`),
+      ref.source,
+    ));
+    return;
+  }
+  if (r.status < 200 || r.status >= 300) {
+    findings.push(finding(
+      'warning', 'XREF_RESOLUTION_SKIPPED', code,
+      locatorDetail(ref, `github ${ref.repo}#${ref.issue} unresolved (HTTP ${r.status})`),
+      ref.source,
+    ));
+    return;
+  }
+  if (!r.body || (r.body.state !== 'open' && r.body.state !== 'closed')) {
+    // 2xx but unparseable/missing state (github-api.js _req coerces JSON
+    // parse failures to {}) — degrade, do not assume a state.
+    findings.push(finding(
+      'warning', 'XREF_RESOLUTION_SKIPPED', code,
+      locatorDetail(ref, `github ${ref.repo}#${ref.issue} returned no parseable issue state (HTTP ${r.status})`),
+      ref.source,
+    ));
+    return;
+  }
+  const state = r.body.state;
+  const drift = githubDrift(ref, state);
+  if (drift) {
+    findings.push(finding('warning', 'XREF_DRIFT', code, locatorDetail(ref, drift), ref.source));
+  }
+}
+
+function resolveLocalRef(ref, cwd, findings) {
+  const code = ref.citing.code || undefined;
+  // Containment guard: repo token must resolve to a direct sibling of cwd.
+  // (The grammar already constrains roadmap citations; this also covers the
+  // feature.json-link carrier and is belt-and-suspenders against traversal.)
+  const parentDir = path.resolve(cwd, '..');
+  const citedRoot = path.resolve(parentDir, String(ref.repo || ''));
+  // Lexical check first (cheap, rejects obvious traversal / separators).
+  let unsafe = !ref.repo || /[\\/]/.test(ref.repo) || ref.repo === '.' || ref.repo === '..'
+    || path.dirname(citedRoot) !== parentDir;
+  // Canonicalize to defeat a valid-named sibling that is a symlink pointing
+  // outside the parent. realpath throws if the path is absent — that is just
+  // "target missing", handled by the same finding below.
+  if (!unsafe) {
+    try {
+      const realParent = fs.realpathSync(parentDir);
+      const realCited = fs.realpathSync(citedRoot);
+      if (path.dirname(realCited) !== realParent) unsafe = true;
+    } catch { unsafe = true; }
+  }
+  if (unsafe) {
+    findings.push(finding(
+      'error', 'XREF_TARGET_MISSING', code,
+      locatorDetail(ref, `local repo token "${ref.repo}" is not a valid sibling directory (missing or escapes the workspace parent)`),
+      ref.source,
+    ));
+    return;
+  }
+  let resolvedStatus = null;
+  try {
+    const paths = resolveProjectPaths(citedRoot);
+    const fjPath = path.join(paths.features, ref.toCode, 'feature.json');
+    if (fs.existsSync(fjPath)) {
+      resolvedStatus = JSON.parse(fs.readFileSync(fjPath, 'utf8')).status || null;
+    } else {
+      // fall back to a ROADMAP row in the cited repo
+      const sub = loadValidationContext(citedRoot, {});
+      resolvedStatus = sub.roadmapByCode.get(ref.toCode)?.status || null;
+    }
+  } catch { resolvedStatus = null; }
+  if (resolvedStatus === null) {
+    findings.push(finding(
+      'error', 'XREF_TARGET_MISSING', code,
+      locatorDetail(ref, `local ${ref.repo} ${ref.toCode} not found (no feature.json or ROADMAP row)`),
+      ref.source,
+    ));
+    return;
+  }
+  let drift = null;
+  if (ref.expect && resolvedStatus !== ref.expect) {
+    drift = `expected ${ref.toCode} to be ${ref.expect} but it is ${resolvedStatus}`;
+  } else if (!ref.expect) {
+    const s = ref.citing.status;
+    if (OPEN_ISH.has(s) && TERMINAL_ISH.has(resolvedStatus) === false && resolvedStatus === 'KILLED') {
+      drift = `citing row is ${s} but ${ref.toCode} is KILLED`;
+    } else if (TERMINAL_ISH.has(s) && OPEN_ISH.has(resolvedStatus)) {
+      drift = `citing row is ${s} but ${ref.toCode} is still ${resolvedStatus}`;
+    }
+  }
+  if (drift) {
+    findings.push(finding('warning', 'XREF_DRIFT', code, locatorDetail(ref, drift), ref.source));
+  }
+}
+
+/**
+ * Read-only external-reference resolution. Extends validateProject; never
+ * writes any file or issue. Gated: full network resolution only when
+ * options.external / COMPOSE_XREF_ONLINE=1 / compose.json xref.prePushOnline.
+ * Degrade contract (spec §6): every resolution failure is a WARNING
+ * (XREF_RESOLUTION_SKIPPED), never an error, never aborts the run.
+ */
+async function runExternalRefChecks(ctx, findings, options = {}) {
+  const cfg = readProjectConfig(ctx.cwd);
+  const citingWorkspaceId = resolveCitingWorkspaceId(ctx.cwd, options, cfg);
+  const refs = collectExternalRefs(ctx, citingWorkspaceId, findings);
+  if (refs.length === 0) return;
+
+  const gateOn = xrefGateOn(options, cfg);
+  let noTokenAggregated = false;
+  let githubShortCircuited = false;
+
+  for (const ref of refs) {
+    const code = ref.citing.code || undefined;
+    try {
+      if (ref.provider === 'local') {
+        resolveLocalRef(ref, ctx.cwd, findings);
+        continue;
+      }
+      if (URL_CLASS.has(ref.provider)) {
+        findings.push(finding(
+          'info', 'XREF_URL_UNCHECKED', code,
+          locatorDetail(ref, `${ref.provider} pointer recorded, not status-resolved: ${ref.url}`),
+          ref.source,
+        ));
+        continue;
+      }
+      if (ref.provider === 'github') {
+        if (!gateOn) {
+          findings.push(finding(
+            'warning', 'XREF_RESOLUTION_SKIPPED', code,
+            locatorDetail(ref, `github ${ref.repo}#${ref.issue} not resolved (network off; pass --external / COMPOSE_XREF_ONLINE=1)`),
+            ref.source,
+          ));
+          continue;
+        }
+        if (githubShortCircuited) {
+          // An aggregate XREF_RESOLUTION_SKIPPED (no-token or rate-limit) was
+          // already emitted for the whole github batch — skip the rest
+          // silently rather than double-counting with a per-ref warning
+          // (and a wrong reason string for the no-token case).
+          continue;
+        }
+        let gh;
+        try {
+          gh = new GitHubApi(
+            { repo: ref.repo, auth: options.githubAuth || { tokenEnv: 'GITHUB_TOKEN' } },
+            options.githubTransport || null,
+          );
+        } catch (e) {
+          if (e && e.name === 'TrackerConfigError' && e.detail && e.detail.missing === 'token') {
+            if (!noTokenAggregated) {
+              noTokenAggregated = true;
+              findings.push(finding(
+                'warning', 'XREF_RESOLUTION_SKIPPED', undefined,
+                'github external refs skipped: no GitHub token (set tracker auth or `gh auth login`)',
+                'xref',
+              ));
+            }
+            githubShortCircuited = true;
+            continue;
+          }
+          findings.push(finding(
+            'warning', 'XREF_RESOLUTION_SKIPPED', code,
+            locatorDetail(ref, `github client init failed: ${e && e.message ? e.message : e}`),
+            ref.source,
+          ));
+          continue;
+        }
+        try {
+          await resolveGithubRef(ref, gh, findings);
+        } catch (e) {
+          if (e && e._rateLimit) {
+            githubShortCircuited = true;
+            findings.push(finding(
+              'warning', 'XREF_RESOLUTION_SKIPPED', undefined,
+              'github external refs skipped: GitHub rate-limited (remaining github refs not resolved this run)',
+              'xref',
+            ));
+            continue;
+          }
+          findings.push(finding(
+            'warning', 'XREF_RESOLUTION_SKIPPED', code,
+            locatorDetail(ref, `github resolution error: ${e && e.message ? e.message : e}`),
+            ref.source,
+          ));
+        }
+        continue;
+      }
+      // unknown provider that slipped past the grammar — treat as url-class info
+      findings.push(finding(
+        'info', 'XREF_URL_UNCHECKED', code,
+        locatorDetail(ref, `provider "${ref.provider}" not resolvable; recorded only`),
+        ref.source,
+      ));
+    } catch (e) {
+      // absolute backstop: a single bad ref never poisons the run
+      findings.push(finding(
+        'warning', 'XREF_RESOLUTION_SKIPPED', code,
+        locatorDetail(ref, `unexpected error resolving ref: ${e && e.message ? e.message : e}`),
+        ref.source,
+      ));
+    }
+  }
+}
+
 export async function validateProject(cwd, options = {}) {
   const ctx = loadValidationContext(cwd, options);
   const findings = [];
@@ -624,6 +982,18 @@ export async function validateProject(cwd, options = {}) {
   runOrphanFolderCheck(ctx, findings);
   runChangelogReferenceCheck(ctx, findings);
   runJournalIndexDriftCheck(ctx, findings);
+  try {
+    await runExternalRefChecks(ctx, findings, options);
+  } catch (e) {
+    // Read-only staleness checks must never abort the validator run
+    // (spec §6: degrade, never hard-fail). Any unexpected pre-loop failure
+    // degrades to a single warning.
+    findings.push(finding(
+      'warning', 'XREF_RESOLUTION_SKIPPED', undefined,
+      `external-reference checks skipped (unexpected error): ${e && e.message ? e.message : e}`,
+      'xref',
+    ));
+  }
 
   return { scope: 'project', validated_at: nowIso(), findings };
 }

package/lib/feature-writer.js

@@ -463,6 +463,14 @@ export async function linkArtifact(cwd, args) {
  */
 export async function linkFeatures(cwd, args) {
   validateCode(args.from_code);
+
+  // COMP-MCP-XREF-SCHEMA #15: external cross-project references. These do NOT
+  // resolve through same-project `to_code` semantics, so the validateCode /
+  // self-link / LINK_KINDS guards below are skipped for kind:"external".
+  if (args.kind === 'external') {
+    return linkFeatureExternal(cwd, args);
+  }
+
   validateCode(args.to_code);
   if (args.from_code === args.to_code) {
     throw new Error(`feature-writer: cannot link a feature to itself ("${args.from_code}")`);
@@ -513,6 +521,144 @@ export async function linkFeatures(cwd, args) {
   });
 }
 
+const XREF_PROVIDERS = new Set(['github', 'local', 'url', 'jira', 'linear', 'notion', 'obsidian']);
+const XREF_URL_CLASS = new Set(['url', 'jira', 'linear', 'notion', 'obsidian']);
+const URI_SCHEME_RE = /^[a-zA-Z][a-zA-Z0-9+\-.]*:\/\//;
+// Carrier equivalence: the feature.json-link carrier must reject exactly what
+// the inline citation grammar (lib/xref-citation.js) rejects at parse time, so
+// a stored link can never carry a value #16's resolver would mishandle.
+const XREF_GITHUB_EXPECT = new Set(['open', 'closed']);
+const XREF_LOCAL_EXPECT = new Set([
+  'PLANNED', 'IN_PROGRESS', 'PARTIAL', 'COMPLETE',
+  'SUPERSEDED', 'PARKED', 'BLOCKED', 'KILLED',
+]);
+// No `#` in either half — the citation grammar uses `#` to delimit the issue
+// (gh_target = owner/name#issue), so a repo token containing `#` is not
+// representable in the inline carrier. Keep both carriers equivalent.
+const XREF_GH_REPO_RE = /^[^\s/#]+\/[^\s/#]+$/;
+const XREF_LOCAL_REPO_RE = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Validate the external link variant in-code (the schema enforces the same
+ * shape on disk; this gives a clear error at the call site). Mirrors
+ * contracts/feature-json.schema.json links external branch.
+ */
+function validateExternalArgs(args) {
+  const p = args.provider;
+  if (!p || !XREF_PROVIDERS.has(p)) {
+    throw new Error(
+      `feature-writer: external link requires provider ∈ {${[...XREF_PROVIDERS].join(', ')}}, got "${p}"`,
+    );
+  }
+  if (p === 'github') {
+    if (!args.repo || !Number.isInteger(args.issue) || args.issue < 1) {
+      throw new Error('feature-writer: external github link requires repo + integer issue ≥ 1');
+    }
+    if (!XREF_GH_REPO_RE.test(args.repo)) {
+      throw new Error(`feature-writer: external github repo "${args.repo}" must be "owner/name"`);
+    }
+    if (args.expect != null && !XREF_GITHUB_EXPECT.has(args.expect)) {
+      throw new Error(`feature-writer: external github expect must be open|closed, got "${args.expect}"`);
+    }
+  } else if (p === 'local') {
+    if (!args.repo || !args.to_code) {
+      throw new Error('feature-writer: external local link requires repo + to_code');
+    }
+    if (!XREF_LOCAL_REPO_RE.test(args.repo) || args.repo === '.' || args.repo === '..') {
+      throw new Error(
+        `feature-writer: external local repo "${args.repo}" must be a single sibling directory name `
+        + '([A-Za-z0-9._-], no path separators or "."/"..")',
+      );
+    }
+    if (!FEATURE_CODE_RE.test(args.to_code)) {
+      throw new Error(
+        `feature-writer: external local to_code "${args.to_code}" must match ${FEATURE_CODE_RE}`,
+      );
+    }
+    if (args.expect != null && !XREF_LOCAL_EXPECT.has(args.expect)) {
+      throw new Error(
+        `feature-writer: external local expect must be one of ${[...XREF_LOCAL_EXPECT].join('|')}, got "${args.expect}"`,
+      );
+    }
+  } else if (XREF_URL_CLASS.has(p)) {
+    if (!args.url) {
+      throw new Error(`feature-writer: external ${p} link (url-class) requires url`);
+    }
+    if (!URI_SCHEME_RE.test(args.url)) {
+      throw new Error(`feature-writer: url must be a valid URI (got: ${args.url})`);
+    }
+    // url-class: `expect` is recorded but never resolved (parity with the
+    // citation grammar, which also accepts but ignores it) — no validation.
+  }
+}
+
+/**
+ * Store a kind:"external" cross-project reference on the source feature.
+ * Idempotency key is (kind=external, provider, repo, issue|to_code|url) so a
+ * re-link of the same external pointer is a noop. Read-only with respect to
+ * the cited repo/issue — this only writes the citing feature.json.
+ */
+async function linkFeatureExternal(cwd, args) {
+  validateExternalArgs(args);
+
+  return maybeIdempotent({ ...args, cwd }, async () => {
+    const provider = await getProvider(cwd);
+    const feature = await provider.getFeature(args.from_code);
+    if (!feature) {
+      throw new Error(`feature-writer: feature "${args.from_code}" not found`);
+    }
+
+    const links = Array.isArray(feature.links) ? [...feature.links] : [];
+    const targetKey = args.provider === 'github'
+      ? String(args.issue)
+      : args.provider === 'local'
+        ? args.to_code
+        : args.url;
+    const matchIdx = links.findIndex(
+      l => l.kind === 'external'
+        && l.provider === args.provider
+        && (l.repo ?? null) === (args.repo ?? null)
+        && (
+          l.provider === 'github' ? String(l.issue) === targetKey
+            : l.provider === 'local' ? l.to_code === targetKey
+              : l.url === targetKey
+        ),
+    );
+
+    if (matchIdx !== -1 && !args.force) {
+      return {
+        from_code: args.from_code, kind: 'external',
+        provider: args.provider, noop: true,
+      };
+    }
+
+    const entry = { kind: 'external', provider: args.provider };
+    if (args.repo != null) entry.repo = args.repo;
+    if (args.issue != null) entry.issue = args.issue;
+    if (args.to_code != null) entry.to_code = args.to_code;
+    if (args.url != null) entry.url = args.url;
+    if (args.expect != null) entry.expect = args.expect;
+    if (args.note) entry.note = args.note;
+
+    if (matchIdx !== -1) links[matchIdx] = entry;
+    else links.push(entry);
+
+    await provider.putFeature(args.from_code, { ...feature, links });
+
+    await safeAppendEvent(cwd, {
+      tool: 'link_features',
+      code: args.from_code,
+      kind: 'external',
+      provider: args.provider,
+      note: args.note,
+      forced: matchIdx !== -1 ? true : undefined,
+      idempotency_key: args.idempotency_key,
+    });
+
+    return { from_code: args.from_code, kind: 'external', provider: args.provider };
+  });
+}
+
 /**
  * Read both canonical and linked artifacts for a feature in one call.
  *
@@ -594,7 +740,18 @@ export async function getFeatureLinks(cwd, args) {
     }
     out.outgoing = (feature.links ?? [])
       .filter(l => !kind || l.kind === kind)
-      .map(l => ({ kind: l.kind, to_code: l.to_code, note: l.note }));
+      .map((l) => (l.kind === 'external'
+        ? {
+            kind: l.kind,
+            provider: l.provider,
+            repo: l.repo,
+            issue: l.issue,
+            url: l.url,
+            to_code: l.to_code,
+            expect: l.expect,
+            note: l.note,
+          }
+        : { kind: l.kind, to_code: l.to_code, note: l.note }));
   }
 
   if (direction === 'incoming' || direction === 'both') {

package/lib/tracker/github-api.js

@@ -12,7 +12,7 @@ function resolveToken(auth = {}, noGhFallback = false) {
 export class GitHubApi {
   constructor(cfg, transport = null) {
     this.repo = cfg.repo;
-    if (!this.repo || !/^[^/]+\/[^/]+$/.test(this.repo)) {
+    if (!this.repo || !/^[^\s/#]+\/[^\s/#]+$/.test(this.repo)) {
       throw new TrackerConfigError(`tracker.github.repo must be "owner/name" (got "${this.repo}")`);
     }
     this.token = resolveToken(cfg.auth, cfg.auth?._noGhFallback || cfg._noGhFallback);
@@ -42,6 +42,13 @@ export class GitHubApi {
     return r.body;
   }
   async getIssue(number) { return (await this._req('GET', `/repos/${this.repo}/issues/${number}`)).body; }
+  /**
+   * GET /repos/:repo/issues/:number — status-returning sibling of getIssue().
+   * Returns { status, body, headers }; does NOT throw on 4xx (mirrors
+   * getRepo()). Used by COMP-MCP-XREF-VALIDATE (#16) to distinguish 404
+   * (target missing) from ≥500 (degrade). Read-only. getIssue() untouched.
+   */
+  async getIssueResult(number) { return this._req('GET', `/repos/${this.repo}/issues/${number}`); }
   async updateIssue(number, patch) { return (await this._req('PATCH', `/repos/${this.repo}/issues/${number}`, patch)).body; }
   async searchFeatureIssues() {
     return (await this._req('GET', `/search/issues?q=repo:${this.repo}+label:compose-feature`)).body.items ?? [];