Enhance source attribution handling and UI in challenge details

- Remove hardcoded source repo references and implement dynamic source URL generation.
- Add source files section in the challenge detail page for better visibility.
- Introduce validation for local source attribution in the audit script.

Author: olivomarco

docs/assets/js/challenge.js

@@ -2,11 +2,6 @@
 (function () {
   'use strict';
 
-  // Home-repo slugs (this live consolidated repo); render as plain text without a hyperlink.
-  const SELF_SOURCE_REPOS = new Set([
-    'microsoft/frontier-agentic-devops-rvas',
-  ]);
-
   let _kiosk = null;
 
   /* Internal challenge link that preserves kiosk state when active */
@@ -91,11 +86,9 @@
     // Attribution
     const attr = document.getElementById('attribution');
     if (attr && c.source_repo) {
-      if (SELF_SOURCE_REPOS.has(c.source_repo)) {
-        attr.innerHTML = `Source: ${FP.esc(c.source_repo)} · ${FP.esc(c.license || 'MIT')} License`;
-      } else {
-        attr.innerHTML = `Source: <a href="https://github.com/${FP.esc(c.source_repo)}" target="_blank" rel="noopener">${FP.esc(c.source_repo)}</a> · ${FP.esc(c.license || 'MIT')} License`;
-      }
+      const sourceUrl = FP.githubSourceUrl(c.source_repo, c.source_path, c.source_ref);
+      const sourceLabel = FP.esc(c.source_repo + (c.source_path ? ` / ${c.source_path}` : ''));
+      attr.innerHTML = `Origin: <a href="${sourceUrl}" target="_blank" rel="noopener">${sourceLabel}</a> · ${FP.esc(c.license || 'MIT')} License`;
     }
   }
 
@@ -170,6 +163,24 @@
         .join('') || '<span class="text-dim" style="font-size:0.8rem">No tags</span>';
     }
 
+    // Exact source files for the two rendered guide views.
+    const sourcePanel = document.getElementById('sourcePanel');
+    const sourceList = document.getElementById('sourceList');
+    if (sourcePanel && sourceList) {
+      const sources = [
+        ['Delivery guide', c.student_source_repo, c.student_source_path],
+        ['Delivery assurance', c.coach_source_repo, c.coach_source_path],
+      ].filter(([, repo, sourcePath]) => repo && sourcePath);
+
+      if (!sources.length) {
+        sourcePanel.style.display = 'none';
+      } else {
+        sourceList.innerHTML = sources.map(([label, repo, sourcePath]) =>
+          `<a href="${FP.githubSourceUrl(repo, sourcePath, c.source_ref)}" target="_blank" rel="noopener" class="attribution" style="display:block;margin-bottom:5px">${FP.esc(label)} ↗</a>`
+        ).join('');
+      }
+    }
+
     // References
     const refPanel = document.getElementById('refPanel');
     const refList  = document.getElementById('refList');

docs/assets/js/core.js

@@ -79,6 +79,13 @@
   FP.catalogOutcomeUrl = function (id) {
     return 'catalog.html?outcome=' + encodeURIComponent(id);
   };
+  FP.githubSourceUrl = function (repo, sourcePath, ref) {
+    const base = 'https://github.com/' +
+      String(repo || '').split('/').map(encodeURIComponent).join('/');
+    if (!sourcePath) return base;
+    return base + '/blob/' + encodeURIComponent(ref || 'main') + '/' +
+      String(sourcePath).split('/').map(encodeURIComponent).join('/');
+  };
   FP.outcomeName = function (outcomeId, outcomes) {
     const o = (outcomes || []).find((x) => x.id === outcomeId);
     return o ? o.name : outcomeId;

docs/build.js

@@ -81,6 +81,8 @@ const OUT_DATA_DIR   = path.join(__dirname, 'assets', 'data');
 const OUT_GUIDES_DIR = path.join(OUT_DATA_DIR, 'challenges');
 const OUT_RESOURCES_DIR = path.join(__dirname, 'resources');
 const OUTCOMES_PATH  = path.join(ROOT, 'outcomes.json');
+const CURRENT_SOURCE_REPO = 'microsoft/frontier-agentic-devops-rvas';
+const CURRENT_SOURCE_REF = process.env.SOURCE_REF || 'main';
 
 /* ─── Minimal YAML parser ────────────────────────────────────────────────────
  * Handles only the locked meta.yml contract: scalar key-value pairs, block
@@ -231,6 +233,21 @@ function readDirSafe(p) {
   catch { return []; }
 }
 
+function relativeSourcePath(file) {
+  return path.relative(ROOT, file).replace(/\\/g, '/');
+}
+
+function validateLocalSourceAttribution(meta, metaPath) {
+  if (meta.source_repo !== CURRENT_SOURCE_REPO) return null;
+
+  const sourcePath = String(meta.source_path || '');
+  const resolved = path.resolve(ROOT, sourcePath);
+  if (!sourcePath || !resolved.startsWith(`${ROOT}${path.sep}`) || !fs.existsSync(resolved)) {
+    return `${relativeSourcePath(metaPath)}: source_path "${sourcePath}" does not resolve in ${CURRENT_SOURCE_REPO}`;
+  }
+  return null;
+}
+
 function rewriteResourceLinksForPages(text, moduleId) {
   const moduleResources = `resources/${moduleId}/`;
   return text.replace(
@@ -407,6 +424,11 @@ function main() {
 
       const raw  = parseMeta(fs.readFileSync(metaPath, 'utf8'));
       const meta = normaliseMeta(raw, moduleId, slug);
+      const sourceAttributionError = validateLocalSourceAttribution(meta, metaPath);
+      if (sourceAttributionError) {
+        console.error(`  ✗ ${sourceAttributionError}`);
+        errors++;
+      }
 
       // Warn on missing recommended fields
       const warnFields = ['description', 'title', 'track', 'difficulty', 'duration_minutes'];
@@ -429,8 +451,8 @@ function main() {
       const hasReadme = copyGuideForPages(path.join(dir, 'README.md'), path.join(guideDir, 'README.md'), moduleId, meta.tier !== 'setup');
       const hasCoach  = copyGuideForPages(path.join(dir, 'COACH.md'),  path.join(guideDir, 'COACH.md'), moduleId);
 
-      if (!hasReadme) { console.warn(`  ! ${meta.id}: no README.md (delivery guide)`); warnings++; }
-      if (!hasCoach)  { console.warn(`  ! ${meta.id}: no COACH.md (coach guide)`);   warnings++; }
+      if (!hasReadme) { console.error(`  ✗ ${meta.id}: no README.md (delivery guide)`); errors++; }
+      if (!hasCoach)  { console.error(`  ✗ ${meta.id}: no COACH.md (coach guide)`);   errors++; }
 
       const trackCfg = (moduleCfg.tracks && moduleCfg.tracks[meta.track]) || {};
 
@@ -456,6 +478,11 @@ function main() {
         references:              meta.references.filter(r => r && r !== 'TODO'),
         source_repo:             meta.source_repo  || '',
         source_path:             meta.source_path  || '',
+        source_ref:              CURRENT_SOURCE_REF,
+        student_source_repo:     CURRENT_SOURCE_REPO,
+        student_source_path:     relativeSourcePath(path.join(dir, 'README.md')),
+        coach_source_repo:       CURRENT_SOURCE_REPO,
+        coach_source_path:       relativeSourcePath(path.join(dir, 'COACH.md')),
         license:                 meta.license,
         student_path:            `assets/data/challenges/${meta.id}/README.md`,
         coach_path:              `assets/data/challenges/${meta.id}/COACH.md`,

docs/challenge.html

@@ -125,6 +125,11 @@ <h1 id="challengeTitle">Loading…</h1>
               <div class="panel-body" id="refList"></div>
             </div>
 
+            <div class="panel" id="sourcePanel">
+              <div class="panel-head">Source files</div>
+              <div class="panel-body" id="sourceList"></div>
+            </div>
+
             <div class="panel" id="relatedPanel">
               <div class="panel-head">Related work packages</div>
               <div class="panel-body">

scripts/audit-content.js

@@ -21,6 +21,7 @@ const CHECK_TERMINOLOGY = process.argv.includes('--terminology');
 const CHECK_REMOVAL = process.argv.includes('--removal');
 const PAGES_HOSTS = new Set(['microsoft.github.io']);
 const PROJECT_SLUG = 'frontier-agentic-devops-rvas';
+const CURRENT_SOURCE_REPO = `microsoft/${PROJECT_SLUG}`;
 
 const state = {
   errors: [],
@@ -264,6 +265,7 @@ function auditGuideSurfaces(challenges) {
       if (titleNeedle && h1 && !titleMatchesHeading(titleNeedle, h1)) {
         addWarning(rel(readmePath), 1, `README title does not include meta title "${c.meta.title}"`);
       }
+
       if (!/^##\s+(Success Criteria|Acceptance Criteria|Verify|Verification)\b/im.test(readme)
         && (!Array.isArray(c.meta.success_criteria) || c.meta.success_criteria.length === 0)) {
         addWarning(rel(readmePath), 0, 'delivery guide has no visible success/verification surface');
@@ -278,6 +280,26 @@ function auditGuideSurfaces(challenges) {
   }
 }
 
+function auditSourceAttribution(challenges) {
+  for (const c of challenges) {
+    const fileRel = rel(c.metaPath);
+    const sourceRepo = String(c.rawMeta.source_repo || '');
+    const sourcePath = String(c.rawMeta.source_path || '');
+
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(sourceRepo)) {
+      addError(fileRel, 0, `source_repo must use owner/repository form: "${sourceRepo}"`);
+      continue;
+    }
+
+    if (sourceRepo !== CURRENT_SOURCE_REPO) continue;
+
+    const resolved = path.resolve(ROOT, sourcePath);
+    if (!sourcePath || !resolved.startsWith(`${ROOT}${path.sep}`) || !fs.existsSync(resolved)) {
+      addError(fileRel, 0, `source_path does not resolve in this repository: "${sourcePath}"`);
+    }
+  }
+}
+
 function normalizeText(value) {
   return String(value)
     .toLowerCase()
@@ -790,6 +812,7 @@ async function main() {
   auditMetaContract(challenges);
   auditPlaceholders(files);
   auditGuideSurfaces(challenges);
+  auditSourceAttribution(challenges);
   auditNumberingGaps(challenges);
   auditCodeFencesAndCommands(files);
   auditLinks(files);