chore: review fixes — stale MCP URL, URL validation, soften hardcoded counts

rachaelrenk · oz-agent · rachaelrenk · commit c20e87865564 · 2026-05-05T12:41:18.000-10:00
- Fix stale /sse path in afdocs-fix MCP example (matches PR #23 fix) - Add URL validation in afdocs_audit.mjs to prevent shell injection - Remove hardcoded baseline score from SKILL.md reporting instructions - Soften hardcoded page counts in known-exceptions.md (varies by run) - Scope page-size exception to /changelog/ only, not all large pages Co-Authored-By: Oz <oz-agent@warp.dev>
diff --git a/.agents/skills/afdocs-audit/SKILL.md b/.agents/skills/afdocs-audit/SKILL.md
@@ -57,7 +57,7 @@ Only include a section if its count is > 0. Never list allowlisted issues under
 
 After running the audit, ALWAYS report the results to the user before taking any action. Include:
 
-1. **Score**: Overall score, grade, and comparison to last known score (82/100 B as of 2026-05-05)
+1. **Score**: Overall score and grade
 2. **Failures first**: List every fail-severity check with its message and fix guidance. These are the most impactful.
 3. **Warnings**: List warning-severity checks with context.
 4. **Allowlisted**: Briefly note any known exceptions that were flagged.
diff --git a/.agents/skills/afdocs-audit/references/known-exceptions.md b/.agents/skills/afdocs-audit/references/known-exceptions.md
@@ -1,17 +1,17 @@
 # AFDocs Known Exceptions
 
-This file lists checks that may flag as warnings or failures but are expected and intentional. When reporting audit results, classify these as "Allowlisted" rather than "Remaining."
+This file lists checks from the afdocs-audit skill that may flag as warnings or failures but are expected and intentional. When reporting audit results, classify these as "Allowlisted" rather than "Remaining."
 
 ## content-start-position
 
 **Expected status**: fail or warn
-**Reason**: 34/50 sampled pages have content starting past 50% of the HTML output. This is inherent to Starlight's layout — sidebar navigation, header markup, and JavaScript/CSS precede the `<main>` content area.
+**Reason**: Sampled pages may have content starting past 50% of the HTML output. This is inherent to Starlight's layout — sidebar navigation, header markup, and JavaScript/CSS precede the `<main>` content area.
 **Mitigation**: The llms.txt directive, `<link rel="alternate" type="text/markdown">` in `<head>`, and `Accept: text/markdown` content negotiation middleware all steer agents to the clean markdown version, bypassing the HTML boilerplate entirely.
 **Action**: No fix needed. This is a structural property of Starlight sites.
 
 ## markdown-content-parity
 
-**Expected status**: warn (7 pages, ~2% average difference)
+**Expected status**: warn (several pages, ~2% average difference)
 **Reason**: False positive. The "missing" segments are numbered heading text like "2. Tabbed File Viewer" where Turndown correctly escapes the period (`### 2\. Tabbed File Viewer`) to prevent markdown parsers from interpreting it as a list item. The content IS present in the markdown — the AFDocs checker's text comparison doesn't account for markdown escaping.
 **Affected pages** (as of 2026-05-05):
 - `/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart/` — step headings
@@ -25,9 +25,9 @@ This file lists checks that may flag as warnings or failures but are expected an
 
 ## page-size-markdown / page-size-html
 
-**Expected status**: warn (1 page between 50K-100K chars)
+**Expected status**: warn — but only allowlist `/changelog/`
 **Reason**: The changelog page (`/changelog/`) is intentionally a single long page (~4,000 lines of MDX). It is excluded from `llms-full.txt` generation due to a `hast-util-to-text` stack overflow, but is still accessible at its URL and indexed by the sitemap.
-**Action**: No fix needed unless the page grows significantly larger. Petra has indicated long pages are lower priority.
+**Action**: If the only flagged page is `/changelog/`, classify as allowlisted. If other pages are flagged, treat those as genuine issues that may need splitting.
 
 ## section-header-quality
 
diff --git a/.agents/skills/afdocs-audit/scripts/afdocs_audit.mjs b/.agents/skills/afdocs-audit/scripts/afdocs_audit.mjs
@@ -52,6 +52,16 @@ function parseArgs(argv) {
 }
 
 function runAfdocsCheck(url) {
+	// Validate URL to prevent shell injection
+	try {
+		const parsed = new URL(url);
+		if (!['http:', 'https:'].includes(parsed.protocol)) {
+			throw new Error(`Invalid protocol: ${parsed.protocol}`);
+		}
+	} catch (e) {
+		throw new Error(`Invalid URL "${url}": ${e.message}`);
+	}
+
 	try {
 		const stdout = execSync(`npx afdocs check ${url} --format json`, {
 			encoding: 'utf8',
diff --git a/.agents/skills/afdocs-fix/SKILL.md b/.agents/skills/afdocs-fix/SKILL.md
@@ -133,12 +133,11 @@ grep -A1 "label:" astro.config.mjs | grep "paths:"
 {
   "name": "Warp Documentation",
   "description": "Search and retrieve Warp documentation.",
-  "url": "https://warp.mcp.kapa.ai/sse",
-  "transport": "sse"
+  "url": "https://warp.mcp.kapa.ai"
 }
 ```
 
-This points to the existing Kapa-hosted MCP server. No custom implementation needed.
+This points to the existing Kapa-hosted MCP server (OAuth-protected). No custom implementation needed.
 
 **Files**: `public/.well-known/mcp.json` (new file)
 

Original file line number	Diff line number	Diff line change
`@@ -133,12 +133,11 @@ grep -A1 "label:" astro.config.mjs \| grep "paths:"`
`133`	`133`	`{`
`134`	`134`	`"name": "Warp Documentation",`
`135`	`135`	`"description": "Search and retrieve Warp documentation.",`
`136`		`- "url": "https://warp.mcp.kapa.ai/sse",`
`137`		`- "transport": "sse"`
	`136`	`+ "url": "https://warp.mcp.kapa.ai"`
`138`	`137`	`}`
`139`	`138`	```
`140`	`139`
`141`		`-This points to the existing Kapa-hosted MCP server. No custom implementation needed.`
	`140`	`+This points to the existing Kapa-hosted MCP server (OAuth-protected). No custom implementation needed.`
`142`	`141`
`143`	`142`	Files: `public/.well-known/mcp.json` (new file)
`144`	`143`