From a7ae7212f5171ec5a4883a5772eed754f592a59f Mon Sep 17 00:00:00 2001
From: Agando <roduccomm@gmail.com>
Date: Fri, 23 Oct 2026 21:32:41 +0200
Subject: fix(newos4): audit names broken refs instead of counting
 documentation (v4.6.86-87)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The reference checker ran /skill-view \S+/ over every skill's prose, so 'skill-view <name>' and a
quoted example in skills-system-guide were counted as missing skills: 'Broken refs: 2' with no
names, both phantom. Placeholders and quoted names are now ignored (trailing punctuation stripped
first), and the survivors are listed in the audit line and in the suggestion.

Verified: clean tree -> Broken refs: 0. A probe skill referencing 'ghost-skill' -> Broken refs: 1
(probe-broken-ref → ghost-skill), while '<name>.' and '"module-management"' in the same file are
ignored.
---
 modules/ext/skill-pack-core.js | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

(limited to 'modules/ext')

diff --git a/modules/ext/skill-pack-core.js b/modules/ext/skill-pack-core.js
index cba77b6..c2c95ba 100644
--- a/modules/ext/skill-pack-core.js
+++ b/modules/ext/skill-pack-core.js
@@ -1195,6 +1195,7 @@ after the behaviour itself was fixed in v4.6.58.`),
         var stale = [];
         var duplicates = [];
         var brokenRefs = 0;
+        var brokenList = [];
 
         // 1. Stale check
         const mg = this.terminal?.moduleManager?.modules?.['MemoryGraphModule'];
@@ -1226,13 +1227,23 @@ after the behaviour itself was fixed in v4.6.58.`),
         }
 
         // 3. Reference check
+        // Documentation is not a reference: `skill-view <name>` and quoted examples inside a skill's
+        // prose were counted as broken skills, so the audit reported 2 phantom breakages and named
+        // neither. Placeholders are skipped and the survivors are listed.
         for (var name of allNames) {
             var content = fs.readFile('/skills/' + name + '.md');
             if (!content) continue;
-            var refs = content.match(/skill-view\s+(\S+)/g) || [];
+            var refs = content.match(/skill-view\s+("[^"]+"|\S+)/g) || [];
             for (var ref of refs) {
-                var refName = ref.replace(/skill-view\s+/, '').replace(/\.md$/, '');
-                if (!fs.readFile('/skills/' + refName + '.md')) brokenRefs++;
+                var refName = ref.replace(/skill-view\s+/, '').replace(/^"|"$/g, '').replace(/\.md$/, '');
+                // prose puts punctuation after an example: "skill-view <name>." — strip it before
+                // deciding whether this is a placeholder or a real skill name
+                refName = refName.replace(/[.,;:!?)]+$/, '');
+                if (!refName || /^<.*>$/.test(refName)) continue;   // `<name>` is a placeholder
+                if (!fs.readFile('/skills/' + refName + '.md')) {
+                    brokenRefs++;
+                    brokenList.push(name + ' → ' + refName);
+                }
             }
         }
 
@@ -1246,14 +1257,14 @@ after the behaviour itself was fixed in v4.6.58.`),
             this.terminal.print('Untracked:      ' + untracked.length + '  (no usage telemetry — NOT stale)', 'info');
         }
         this.terminal.print('Duplicates:     ' + duplicates.length + (duplicates.length > 0 ? '  (' + duplicates.join(', ') + ')' : ''), duplicates.length > 0 ? 'warning' : 'info');
-        this.terminal.print('Broken refs:    ' + brokenRefs, brokenRefs > 0 ? 'error' : 'info');
+        this.terminal.print('Broken refs:    ' + brokenRefs + (brokenRefs > 0 ? '  (' + brokenList.join(', ') + ')' : ''), brokenRefs > 0 ? 'error' : 'info');
         this.terminal.print('', '');
 
         if (stale.length > 0 || duplicates.length > 0 || brokenRefs > 0) {
             this.terminal.print('Suggestions:', 'info');
             for (var st of stale) this.terminal.print('• Archive ' + st, 'warning');
             for (var dup of duplicates) this.terminal.print('• Merge ' + dup, 'warning');
-            if (brokenRefs > 0) this.terminal.print('• Fix ' + brokenRefs + ' broken reference(s)', 'warning');
+            if (brokenRefs > 0) this.terminal.print('• Fix ' + brokenRefs + ' broken reference(s): ' + brokenList.join(', '), 'warning');
         } else {
             this.terminal.print('✅ All skills healthy', 'success');
         }
-- 
cgit v1.2.3