dotmd-cli 0.34.0 → 0.35.0

package/README.md

@@ -757,6 +757,12 @@ export const referenceFields = {
   bidirectional: ['related_plans'],       // warn if A→B but B↛A
   unidirectional: ['supports_plans'],     // one-way, no symmetry check
 };
+// Per-ref opt-out: prefix any value with `>` to mark that specific ref one-way
+// without changing the field's default. Useful for leaf→upstream-parent refs
+// (audits, hub docs) where a back-ref would force editing a stable parent.
+//   related_docs:
+//     - docs/sibling-design.md            # bidirectional (default for the field)
+//     - "> docs/audit-beyond-platform.md" # one-way upstream — no back-ref expected
 
 export const index = {
   path: 'docs/docs.md',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/index.mjs

@@ -175,10 +175,30 @@ export function parseDocFile(filePath, config) {
   const bodyLinks = extractBodyLinks(body);
   const hasCloseout = /^##\s+Closeout/m.test(body);
 
-  // Dynamic reference field extraction
+  // Dynamic reference field extraction. A leading `>` on a value (e.g.
+  // `"> docs/audit-beyond-platform.md"`) marks that single ref as one-way —
+  // the prefix is stripped so path resolution still works, and the direction
+  // is recorded on a parallel `refFieldDirections[field]` array indexed the
+  // same as `refFields[field]`. Bidirectional reciprocity checks consume the
+  // directions to skip outbound entries that opted out of expecting a back-ref.
   const refFields = {};
+  const refFieldDirections = {};
   for (const field of [...(config.referenceFields.bidirectional || []), ...(config.referenceFields.unidirectional || [])]) {
-    refFields[field] = normalizeStringList(parsedFrontmatter[field]);
+    const raw = normalizeStringList(parsedFrontmatter[field]);
+    const paths = [];
+    const directions = [];
+    for (const entry of raw) {
+      const oneWay = entry.match(/^>\s*(.+)$/);
+      if (oneWay) {
+        paths.push(oneWay[1].trim());
+        directions.push('one-way');
+      } else {
+        paths.push(entry);
+        directions.push('two-way');
+      }
+    }
+    refFields[field] = paths;
+    refFieldDirections[field] = directions;
   }
 
   // Tag doc with its root
@@ -215,6 +235,7 @@ export function parseDocFile(filePath, config) {
     checklist,
     bodyLinks,
     refFields,
+    refFieldDirections,
     checklistCompletionRate: computeChecklistCompletionRate(checklist),
     hasCloseout,
     hasNextStep: Boolean(nextStep),

package/src/validate.mjs

@@ -258,26 +258,42 @@ export function checkBidirectionalReferences(docs, config) {
   const biFields = config.referenceFields.bidirectional || [];
   if (!biFields.length) return { warnings, errors: [] };
 
+  // refMap stores `Set<targetPath>` keyed by the source doc path — used to
+  // answer "does B reference A?" via .has(). oneWayMap stores the subset of A's
+  // outbound refs that opted out of expecting a back-ref (via the `>` prefix in
+  // frontmatter, parsed in src/index.mjs:parseDocFile). We split these so the
+  // membership check stays cheap (Set.has) while the per-ref directionality
+  // filter only consults oneWayMap when iterating outbound edges.
   const refMap = new Map();
+  const oneWayMap = new Map();
   for (const doc of docs) {
     const docDir = path.dirname(path.join(config.repoRoot, doc.path));
     const refs = new Set();
+    const oneWay = new Set();
     for (const field of biFields) {
-      for (const relPath of (doc.refFields[field] || [])) {
+      const entries = doc.refFields[field] || [];
+      const dirs = doc.refFieldDirections?.[field] || [];
+      for (let i = 0; i < entries.length; i++) {
+        const relPath = entries[i];
         // Use the same doc-relative-then-repo-root fallback as validateDoc so
         // both styles produce identical refMap keys; otherwise an entry like
         // `docs/foo.md` (repo-root style) gets keyed as
         // `<doc-parent>/docs/foo.md` and never matches the target's repo path.
         const resolved = resolveRefPath(relPath, docDir, config.repoRoot)
           ?? path.resolve(docDir, relPath);
-        refs.add(toRepoPath(resolved, config.repoRoot));
+        const targetPath = toRepoPath(resolved, config.repoRoot);
+        refs.add(targetPath);
+        if (dirs[i] === 'one-way') oneWay.add(targetPath);
       }
     }
     refMap.set(doc.path, refs);
+    oneWayMap.set(doc.path, oneWay);
   }
 
   for (const [docPath, refs] of refMap) {
+    const oneWay = oneWayMap.get(docPath);
     for (const targetPath of refs) {
+      if (oneWay.has(targetPath)) continue;
       const targetRefs = refMap.get(targetPath);
       if (targetRefs && !targetRefs.has(docPath)) {
         warnings.push({ path: docPath, level: 'warning',