@smartmemory/compose 0.1.37-beta → 0.1.39-beta

package/bin/compose.js

@@ -1589,6 +1589,7 @@ if (cmd === 'validate') {
   let code = null
   let blockOn = 'error'
   let asJson = false
+  let externalXref = false
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
     if (a === '--help' || a === '-h') {
@@ -1608,6 +1609,7 @@ Exit codes:
       process.exit(0)
     }
     if (a === '--json') { asJson = true; continue }
+    if (a === '--external') { externalXref = true; continue }
     if (a.startsWith('--scope=')) scope = a.slice('--scope='.length)
     else if (a === '--scope') scope = args[++i]
     else if (a.startsWith('--code=')) code = a.slice('--code='.length)
@@ -1638,7 +1640,7 @@ Exit codes:
   try {
     result = scope === 'feature'
       ? await validateFeature(valCwd, code)
-      : await validateProject(valCwd)
+      : await validateProject(valCwd, { external: externalXref })
   } catch (err) {
     if (err.code === 'INVALID_INPUT') {
       console.error(`Error [INVALID_INPUT]: ${err.message}`)

package/bin/git-hooks/pre-push.template

@@ -2,6 +2,14 @@
 # Compose pre-push hook — runs `compose validate` and blocks the push on
 # any error-severity drift finding. Installed by `compose hooks install --pre-push`;
 # placeholders below are substituted at install time.
+#
+# External-reference (xref) resolution is OFF here by default: github xref:
+# citations / kind:"external" links emit XREF_RESOLUTION_SKIPPED (warning,
+# non-blocking under --block-on=error) while local/url/malformed still
+# surface. Opt in to network github resolution by exporting
+# COMPOSE_XREF_ONLINE=1, or set `xref.prePushOnline: true` in
+# .compose/compose.json — both are honored by `compose validate` directly
+# (no flag change needed below). XREF_TARGET_MISSING stays error and blocks.
 
 set -u
 COMPOSE_NODE="__COMPOSE_NODE__"

package/contracts/feature-json.schema.json

@@ -68,12 +68,62 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["kind", "to_code"],
         "properties": {
-          "kind": { "type": "string", "enum": ["surfaced_by", "blocks", "depends_on", "follow_up", "supersedes", "related"] },
+          "kind": { "type": "string", "enum": ["surfaced_by", "blocks", "depends_on", "follow_up", "supersedes", "related", "external"] },
           "to_code": { "type": "string", "pattern": "^[A-Z][A-Z0-9-]*[A-Z0-9]$" },
-          "note": { "type": "string" }
-        }
+          "note": { "type": "string" },
+          "provider": { "type": "string", "enum": ["github", "local", "url", "jira", "linear", "notion", "obsidian"] },
+          "repo": { "type": "string" },
+          "issue": { "type": "integer", "minimum": 1 },
+          "url": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9+\\-.]*://" },
+          "expect": { "type": "string" }
+        },
+        "allOf": [
+          {
+            "if": { "not": { "required": ["kind"], "properties": { "kind": { "const": "external" } } } },
+            "then": { "required": ["kind", "to_code"] }
+          },
+          {
+            "if": { "properties": { "kind": { "const": "external" } }, "required": ["kind"] },
+            "then": {
+              "required": ["provider"],
+              "allOf": [
+                {
+                  "if": { "properties": { "provider": { "const": "github" } }, "required": ["provider"] },
+                  "then": {
+                    "required": ["repo", "issue"],
+                    "properties": {
+                      "repo": { "pattern": "^[^\\s/#]+/[^\\s/#]+$" },
+                      "expect": { "enum": ["open", "closed"] }
+                    }
+                  }
+                },
+                {
+                  "if": { "properties": { "provider": { "const": "local" } }, "required": ["provider"] },
+                  "then": {
+                    "required": ["repo", "to_code"],
+                    "properties": {
+                      "repo": {
+                        "pattern": "^[A-Za-z0-9._-]+$",
+                        "not": { "enum": [".", ".."] }
+                      },
+                      "expect": { "enum": ["PLANNED", "IN_PROGRESS", "PARTIAL", "COMPLETE", "SUPERSEDED", "PARKED", "BLOCKED", "KILLED"] }
+                    }
+                  }
+                },
+                {
+                  "if": { "properties": { "provider": { "enum": ["url", "jira", "linear", "notion", "obsidian"] } }, "required": ["provider"] },
+                  "then": {
+                    "required": ["url"],
+                    "properties": {
+                      "url": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9+\\-.]*://" }
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        ]
       }
     },
     "completions": {

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 ?? [];

package/lib/xref-citation.js

@@ -0,0 +1,235 @@
+/**
+ * xref-citation.js — pure parser for inline cross-project external-reference
+ * citations embedded in a ROADMAP/description cell (COMP-MCP-XREF-SCHEMA, #15).
+ *
+ * A citation is an HTML comment so it renders invisibly in markdown:
+ *
+ *   <!-- xref: github owner/repo#123 expect=open -->
+ *   <!-- xref: github smartmemory/compose#7 expect=closed note="shipped X" -->
+ *   <!-- xref: local compose COMP-MCP-VALIDATE expect=COMPLETE -->
+ *   <!-- xref: url https://example.com/spec note="design ref" -->
+ *
+ * Grammar (spec §3.1 EBNF):
+ *   citation   = "<!--" ws "xref:" ws provider ws target
+ *                [ ws "expect=" expect ] [ ws "note=" qstring ] ws "-->"
+ *   provider   = "github" | "local" | "url"                       ; resolvable
+ *              | "jira" | "linear" | "notion" | "obsidian"         ; reserved url-class
+ *   gh_target  = repo "#" issue          ; repo = owner "/" name
+ *   local_target = repo_token ws feature_code
+ *   url_target = URL                     ; url + every reserved provider
+ *
+ * This module performs ZERO I/O and ZERO network. It is a pure
+ * string → object function. Consumed by #16 (`runExternalRefChecks`); #15
+ * ships it standalone with no caller in the validator path.
+ */
+
+// url-class = `url` + every reserved provider (carry a url_target, never
+// resolved in v1). ALL_PROVIDERS is the full accepted set.
+const RESOLVABLE_PROVIDERS = ['github', 'local', 'url'];
+const RESERVED_PROVIDERS = ['jira', 'linear', 'notion', 'obsidian'];
+const ALL_PROVIDERS = new Set([...RESOLVABLE_PROVIDERS, ...RESERVED_PROVIDERS]);
+
+const GITHUB_EXPECT = new Set(['open', 'closed']);
+const LOCAL_EXPECT = new Set([
+  'PLANNED', 'IN_PROGRESS', 'PARTIAL', 'COMPLETE',
+  'SUPERSEDED', 'PARKED', 'BLOCKED', 'KILLED',
+]);
+const FEATURE_CODE_RE = /^[A-Z][A-Z0-9-]*[A-Z0-9]$/;
+const URI_SCHEME_RE = /^[a-zA-Z][a-zA-Z0-9+\-.]*:\/\//;
+
+// Anchored scan: only HTML comments whose body begins with `xref:` are
+// considered. Any other `<!-- ... -->` is ignored entirely.
+const CITATION_RE = /<!--\s*xref:\s*([\s\S]*?)\s*-->/g;
+
+/**
+ * Structured parse error for a comment that matched `<!--\s*xref:` but
+ * failed the grammar. Consumed by #16 as the `XREF_MALFORMED` finding;
+ * #15 only surfaces it via the return value (never throws, never logs).
+ */
+export class ParseError {
+  constructor(raw, reason) {
+    this.raw = raw;
+    this.reason = reason;
+  }
+}
+
+/**
+ * @typedef {object} PartialExternalRef
+ * @property {string} provider
+ * @property {string|null} repo     github "owner/name" | local repo token | null
+ * @property {number|null} issue    github only
+ * @property {string|null} toCode   local only (target feature code)
+ * @property {string|null} url      url-class only (url + reserved providers)
+ * @property {string|null} expect   optional expected-state token
+ * @property {string|null} note
+ * @property {string} raw           the citation body (for locatability)
+ */
+
+/**
+ * Parse every `xref:` citation in a description cell.
+ * @param {string} descriptionCell
+ * @returns {{ refs: PartialExternalRef[], errors: ParseError[] }}
+ */
+export function parseCitations(descriptionCell) {
+  const refs = [];
+  const errors = [];
+  if (typeof descriptionCell !== 'string' || descriptionCell.length === 0) {
+    return { refs, errors };
+  }
+
+  CITATION_RE.lastIndex = 0;
+  let m;
+  while ((m = CITATION_RE.exec(descriptionCell)) !== null) {
+    const raw = m[1];
+    try {
+      refs.push(parseOne(raw));
+    } catch (e) {
+      if (e instanceof ParseError) errors.push(e);
+      else errors.push(new ParseError(raw, String(e && e.message ? e.message : e)));
+    }
+  }
+  return { refs, errors };
+}
+
+function parseOne(raw) {
+  let rest = raw.trim();
+  if (rest.length === 0) throw new ParseError(raw, 'empty xref citation');
+
+  // Optional trailing options `expect=<tok>` and `note="..."`, order-
+  // independent. They are stripped **end-anchored** (must be the trailing
+  // whitespace-separated token), so a `note=`/`expect=` substring inside the
+  // target itself — e.g. a URL query `https://x/?note=a&expect=b` — is left
+  // in the target and never mis-consumed. Each option may appear at most once.
+  //
+  // Known v1 limitations (faithful to spec §3.1 EBNF, which defines
+  // `qstring = DQUOTE *CHAR DQUOTE` with no escape and an HTML-comment
+  // carrier): a `note="..."` value cannot contain `"` or the literal `-->`.
+  let note = null;
+  let expect = null;
+  for (let i = 0; i < 2; i++) {
+    let m;
+    if (note === null && (m = rest.match(/\s+note="([^"]*)"\s*$/))) {
+      note = m[1];
+      rest = rest.slice(0, m.index).trimEnd();
+      continue;
+    }
+    if (expect === null && (m = rest.match(/\s+expect=(\S+)\s*$/))) {
+      expect = m[1];
+      rest = rest.slice(0, m.index).trimEnd();
+      continue;
+    }
+    break;
+  }
+  // A `note=` option token that exists but was not consumable as a trailing
+  // quoted string is a hard parse error (don't silently fold it into target).
+  if (note === null && /(^|\s)note=/.test(rest)) {
+    if (/(^|\s)note="/.test(rest)) {
+      throw new ParseError(raw, 'unterminated or misplaced note="..." (must be a trailing double-quoted token)');
+    }
+    throw new ParseError(raw, 'note= value must be a double-quoted string');
+  }
+  // Likewise a stray trailing `expect=` token that wasn't consumed.
+  if (expect === null && /(^|\s)expect=\S*\s*$/.test(rest)) {
+    throw new ParseError(raw, 'malformed expect= option');
+  }
+  rest = rest.replace(/\s+/g, ' ').trim();
+
+  // Remaining: `<provider> <target...>`.
+  const firstWs = rest.search(/\s/);
+  if (firstWs === -1) {
+    throw new ParseError(raw, `missing target after provider "${rest}"`);
+  }
+  const provider = rest.slice(0, firstWs);
+  const target = rest.slice(firstWs + 1).trim();
+
+  if (!ALL_PROVIDERS.has(provider)) {
+    throw new ParseError(
+      raw,
+      `unknown provider "${provider}" (expected one of ${[...ALL_PROVIDERS].join(', ')})`,
+    );
+  }
+  if (target.length === 0) {
+    throw new ParseError(raw, `missing target for provider "${provider}"`);
+  }
+
+  const ref = {
+    provider,
+    repo: null,
+    issue: null,
+    toCode: null,
+    url: null,
+    expect: null,
+    note,
+    raw,
+  };
+
+  if (provider === 'github') {
+    // No `#` in either repo half — `#` delimits the issue (owner/name#issue)
+    // and GitHub owners/names cannot contain it. Keeps the citation carrier
+    // carrier-equivalent with the feature.json-link writer (XREF_GH_REPO_RE).
+    const gh = target.match(/^([^\s/#]+\/[^\s/#]+)#(\d+)$/);
+    if (!gh) {
+      throw new ParseError(raw, `github target must be "owner/name#issue", got "${target}"`);
+    }
+    ref.repo = gh[1];
+    ref.issue = Number(gh[2]);
+    if (expect !== null) {
+      if (!GITHUB_EXPECT.has(expect)) {
+        throw new ParseError(
+          raw, `github expect must be open|closed, got "${expect}"`,
+        );
+      }
+      ref.expect = expect;
+    }
+  } else if (provider === 'local') {
+    const parts = target.split(/\s+/);
+    if (parts.length !== 2) {
+      throw new ParseError(
+        raw, `local target must be "<repo> <FEATURE_CODE>", got "${target}"`,
+      );
+    }
+    const [repoTok, code] = parts;
+    // repo token must be a single safe directory name — it is resolved as a
+    // sibling dir (path.join(cwd, '..', repoTok)); reject anything with a
+    // path separator or traversal so a citation cannot escape the workspace.
+    if (!/^[A-Za-z0-9._-]+$/.test(repoTok) || repoTok === '.' || repoTok === '..') {
+      throw new ParseError(
+        raw,
+        `local repo token "${repoTok}" must be a single directory name `
+        + '([A-Za-z0-9._-], no path separators or "."/"..")',
+      );
+    }
+    if (!FEATURE_CODE_RE.test(code)) {
+      throw new ParseError(raw, `local target feature code "${code}" is not a valid code`);
+    }
+    ref.repo = repoTok;
+    ref.toCode = code;
+    if (expect !== null) {
+      if (!LOCAL_EXPECT.has(expect)) {
+        throw new ParseError(
+          raw,
+          `local expect must be one of ${[...LOCAL_EXPECT].join('|')}, got "${expect}"`,
+        );
+      }
+      ref.expect = expect;
+    }
+  } else {
+    // url-class: provider `url` and every reserved provider. The target is a
+    // single URL token; `expect=` is syntactically accepted but ignored
+    // (these refs are never resolved in v1 — spec §5.2/§9), never a ParseError.
+    if (/\s/.test(target)) {
+      throw new ParseError(
+        raw, `${provider} target must be a single URL, got "${target}"`,
+      );
+    }
+    if (!URI_SCHEME_RE.test(target)) {
+      throw new ParseError(
+        raw, `${provider} target must be a scheme:// URL, got "${target}"`,
+      );
+    }
+    ref.url = target;
+    if (expect !== null) ref.expect = expect; // recorded, not validated, not resolved
+  }
+
+  return ref;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.1.37-beta",
+  "version": "0.1.39-beta",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",

package/server/compose-mcp-tools.js

@@ -291,10 +291,11 @@ export async function toolValidateFeature(args = {}) {
 
 export async function toolValidateProject(args = {}) {
   const { validateProject } = await import('../lib/feature-validator.js');
-  const { external_prefixes, feature_json_mode } = args;
+  const { external_prefixes, feature_json_mode, external } = args;
   return validateProject(getTargetRoot(), {
     externalPrefixes: external_prefixes,
     featureJsonMode: feature_json_mode,
+    external: external === true,
   });
 }
 

package/server/compose-mcp.js

@@ -363,12 +363,13 @@ const TOOLS = [
   },
   {
     name: 'validate_project',
-    description: 'Run validate_feature for every code in vision-state, ROADMAP, and folders, plus cross-cutting checks (orphan folders, dangling cross-refs, CHANGELOG references, journal index drift). Returns the union of all findings.',
+    description: 'Run validate_feature for every code in vision-state, ROADMAP, and folders, plus cross-cutting checks (orphan folders, dangling cross-refs, CHANGELOG references, journal index drift) and read-only external-reference staleness (kind:"external" links + xref: roadmap citations). external:true enables network resolution of github refs (off by default — github refs then emit XREF_RESOLUTION_SKIPPED). Returns the union of all findings.',
     inputSchema: {
       type: 'object',
       properties: {
         external_prefixes: { type: 'array', items: { type: 'string' } },
         feature_json_mode: { type: 'boolean' },
+        external: { type: 'boolean', description: 'Resolve github external refs over the network (read-only). Default false: github refs degrade to XREF_RESOLUTION_SKIPPED.' },
       },
     },
   },
@@ -411,14 +412,19 @@ const TOOLS = [
   },
   {
     name: 'link_features',
-    description: 'Register a typed cross-feature relationship. Stores on the source feature; query the inverse via get_feature_links(direction:"incoming"). Closed enum on kind; self-links rejected; dedups on (kind, to_code).',
+    description: 'Register a typed cross-feature relationship. Two shapes: (1) SAME-PROJECT — kind ∈ surfaced_by|blocks|depends_on|follow_up|supersedes|related, requires to_code; self-links rejected; dedups on (kind,to_code). (2) EXTERNAL (kind:"external") — a cross-project pointer, NOT a same-project link: requires provider; three resolvable sub-shapes — github (repo "owner/name" + integer issue), local (repo token + to_code), url (url); plus reserved url-class providers jira|linear|notion|obsidian (parse-valid, require url, NOT resolved in v1). External dedups on (kind=external, provider, repo, issue|to_code|url). Stores on the source feature; query inverse via get_feature_links(direction:"incoming").',
     inputSchema: {
       type: 'object',
-      required: ['from_code', 'to_code', 'kind'],
+      required: ['from_code', 'kind'],
       properties: {
         from_code: { type: 'string' },
-        to_code: { type: 'string', description: 'Target feature code. Need not exist yet (you can link to a code you are about to create).' },
-        kind: { type: 'string', enum: ['surfaced_by', 'blocks', 'depends_on', 'follow_up', 'supersedes', 'related'] },
+        to_code: { type: 'string', description: 'Same-project: target feature code (required unless kind:"external"). External local: the cited feature code. Need not exist yet.' },
+        kind: { type: 'string', enum: ['surfaced_by', 'blocks', 'depends_on', 'follow_up', 'supersedes', 'related', 'external'] },
+        provider: { type: 'string', enum: ['github', 'local', 'url', 'jira', 'linear', 'notion', 'obsidian'], description: 'Required when kind:"external". Resolvable: github|local|url. Reserved url-class (require url, not resolved in v1): jira|linear|notion|obsidian.' },
+        repo: { type: 'string', description: 'External github: "owner/name". External local: workspace-relative repo token.' },
+        issue: { type: 'integer', minimum: 1, description: 'External github: issue/PR number.' },
+        url: { type: 'string', description: 'External url-class (url|jira|linear|notion|obsidian): the pointer URL.' },
+        expect: { type: 'string', description: 'Optional expected state. github: open|closed. local: a status token. url-class: recorded, never resolved.' },
         note: { type: 'string' },
         force: { type: 'boolean' },
         idempotency_key: { type: 'string' },