AI Doc Consistency & Lint #20

Workflow file for this run

.github/workflows/doc-architecture-enforcer.yaml at 949a2e4

	# DOC/ARCHITECTURE CONSISTENCY ENFORCER WORKFLOW
	#
	# HTML-CSS-FIRST, ZERO-DEPENDENCY, BROWSER-NATIVE ARCHITECTURE ENFORCER
	#
	# Checks ALL README.md, PROJECT-STATE.md, AGENT.md, AGENTS.md, .github/copilot-instructions.md
	# ... (rest of your top-level rationale comments)
	#
	# CRITICAL: HTML-CSS-First Hidden Checkbox Pattern
	# NEVER "fix" this - it's intentionally advanced:
	# <label role="button" name="submit" aria-label="Save">
	# Save
	# <input type="checkbox" /> <!-- CSS state hook -->
	# </label>
	# Why: 100-1000x faster than JS, secure, accessible, works without JS.
	# Rules: Never replace with <button>, never add JS event handlers.
	#
	# Architecture Rules:
	# - HTML: Semantic only. No classes, IDs, data-*, inline styles/scripts. Action labels need role="button".
	# - CSS: ALL UI logic via :has(), :checked, :valid, :empty, @container. Hidden checkboxes = state machines for CSS.
	# - JS: Data-only (fetch/inject/ARIA). NO DOM manipulation, event listeners, or UI logic. Use oninput/onchange only.
	#
	# Code Patterns:
	# - Progressive enhancement (works JS-off)
	# - Holy Grail layout via <app-container>
	# - Forms in <fieldset> with schema/rules
	# - Custom elements from JSON (toTagName())
	# - aria-disabled for accessibility (CSS styles it)
	# - Checkbox :checked drives panel visibility, loading states, complex UI
	#
	# JS Constraints:
	# - Must be idempotent/stateless
	# - Reuse existing functions before creating new
	# - Use schema.js for data consistency
	# - No global state, side effects, or DOM styling
	# - Only manage data flow + ARIA attributes
	#
	# File Roles:
	# - forms.js: form state + ARIA management
	# - inject.js: DOM content injection from JSON
	# - loaders.js: fetch + inject using schema/rules
	# - utils.js: stateless helpers only
	# - config.js: constants only
	#
	# Key: This is advanced web standards, not "outdated" patterns. Preserve exactly as implemented.

	name: AI Doc Consistency & Lint

	on:
	pull_request:
	paths:
	- '*/.js'
	- '*/.css'
	- '*/.html'
	- '.github/copilot-instructions.md'
	- 'PROJECT-STATE.md'
	- 'README.md'
	- 'AGENT.md'
	- 'AGENTS.md'
	schedule:
	- cron: "0 3 * * 1" # Weekly, Mondays at 03:00 UTC

	jobs:
	lint-docs:
	name: Lint AI Docs for Forbidden Patterns
	runs-on: ubuntu-latest
	steps:
	- uses: actions/checkout@v4
	- name: Lint for forbidden patterns
	run: \|
	# Enforce D7460N/DHCP doc architecture: no classes, IDs, data-*, <button>, event listeners, or inline scripts/styles
	BAD_PATTERNS='class=\|id=\|data-\|<button\|addEventListener\|on(click\|focus\|blur\|keydown\|keyup\|mousedown\|mouseup\|mouseenter\|mouseleave\|touchstart\|touchend\|touchmove)\|style='
	DOCS="$(find . -type f -iname 'README.md' -o -name 'PROJECT-STATE.md' -o -name 'AGENT.md' -o -name 'AGENTS.md' -o -path './.github/copilot-instructions.md')"

	# Create temporary file to capture detailed output
	LINT_OUTPUT=$(mktemp)

	set +e
	grep -nE "$BAD_PATTERNS" $DOCS > "$LINT_OUTPUT" 2>&1
	STATUS=$?
	set -e

	if [ $STATUS -eq 0 ]; then
	echo "❌ Forbidden pattern found in docs. Details:" >&2
	cat "$LINT_OUTPUT" >&2

	# Save detailed output for issue creation
	echo "LINT_FAILURES<<EOF" >> $GITHUB_ENV
	cat "$LINT_OUTPUT" >> $GITHUB_ENV
	echo "EOF" >> $GITHUB_ENV

	# Count of failures for summary
	FAILURE_COUNT=$(wc -l < "$LINT_OUTPUT")
	echo "LINT_FAILURE_COUNT=$FAILURE_COUNT" >> $GITHUB_ENV

	rm "$LINT_OUTPUT"
	exit 1
	else
	echo "✅ Docs lint clean."
	echo "LINT_FAILURES=" >> $GITHUB_ENV
	echo "LINT_FAILURE_COUNT=0" >> $GITHUB_ENV
	rm "$LINT_OUTPUT"
	fi

	doc-drift:
	name: Detect Doc Drift (Architecture/AI Context)
	runs-on: ubuntu-latest
	permissions:
	contents: read
	steps:
	- uses: actions/checkout@v4
	- name: Check for doc drift
	run: \|
	# Patterns that define the architecture (expand as needed)
	PATTERNS='input type="checkbox"\|:has$\|@container\|fieldset\|aria-label\|role="button"\|Holy Grail\|progressive enhancement\|toTagName\($\|aria-disabled\|:empty\|:valid'
	CODE_PATTERNS=$(grep -Ero "$PATTERNS" . --include=.html --include=.css --include=.js \| sed 's/.://g' \| sort \| uniq)
	DOC_PATTERNS=$(grep -Ero "$PATTERNS" README.md PROJECT-STATE.md .github/copilot-instructions.md AGENT.md AGENTS.md \| sed 's/.*://g' \| sort \| uniq)

	MISSING_DOCS=""
	for pat in $CODE_PATTERNS; do
	echo "$DOC_PATTERNS" \| grep -qF "$pat" \|\| MISSING_DOCS="$MISSING_DOCS $pat"
	done

	if [ -n "$MISSING_DOCS" ]; then
	echo "❌ Architectural patterns present in code but not in docs:"
	echo "$MISSING_DOCS"

	# Save detailed drift information for issue creation
	echo "DRIFT_FAILURES<<EOF" >> $GITHUB_ENV
	echo "Missing architectural patterns in documentation:" >> $GITHUB_ENV
	for pat in $MISSING_DOCS; do
	echo "• $pat" >> $GITHUB_ENV
	# Show where the pattern appears in code
	echo " Found in code:" >> $GITHUB_ENV
	grep -rn "$pat" . --include=.html --include=.css --include=*.js \| head -3 \| sed 's/^/ /' >> $GITHUB_ENV
	done
	echo "EOF" >> $GITHUB_ENV

	DRIFT_COUNT=$(echo "$MISSING_DOCS" \| wc -w)
	echo "DRIFT_FAILURE_COUNT=$DRIFT_COUNT" >> $GITHUB_ENV

	exit 1
	else
	echo "✅ No doc drift detected."
	echo "DRIFT_FAILURES=" >> $GITHUB_ENV
	echo "DRIFT_FAILURE_COUNT=0" >> $GITHUB_ENV
	fi

	notify-on-failure:
	name: Notify on Failure
	needs: [lint-docs, doc-drift]
	runs-on: ubuntu-latest
	if: failure()
	permissions:
	issues: write
	contents: none
	pull-requests: none
	steps:
	- name: Create Issue for Drift/Lint Failure
	uses: dacbd/create-issue-action@v1
	with:
	title: "AI Doc Consistency/Lint Failure"
	token: ${{ secrets.GITHUB_TOKEN }}
	body: \|
	One or more AI documentation files have failed lint or drift detection.

	## 📊 Failure Summary

	- Forbidden Pattern Violations: ${{ env.LINT_FAILURE_COUNT \|\| '0' }}
	- Documentation Drift Issues: ${{ env.DRIFT_FAILURE_COUNT \|\| '0' }}

	## 🚨 Forbidden Pattern Violations

	${{ env.LINT_FAILURES && format('The following forbidden patterns were found in documentation files:

	```
	{0}
	```

	Common fixes:
	- Replace `<button>` with `<label role="button"><input type="checkbox" /></label>`
	- Remove `class=`, `id=`, and `data-*` attributes
	- Replace `addEventListener` and `onclick` with `oninput`/`onchange`
	- Remove inline `style=` attributes
	', env.LINT_FAILURES) \|\| 'No forbidden pattern violations detected.' }}

	## 📋 Documentation Drift Issues

	${{ env.DRIFT_FAILURES \|\| 'No documentation drift detected.' }}

	## ✅ Action Required

	For Forbidden Patterns:
	- Review the specific files and line numbers listed above
	- Align `.github/copilot-instructions.md`, `PROJECT-STATE.md`, `README.md`, `AGENT.md`, and `AGENTS.md` with current repo architecture
	- Remove forbidden patterns (classes, IDs, data-*, `<button>`, event listeners, inline styles/scripts, etc)

	For Documentation Drift:
	- Document all architectural patterns found in code within the documentation files
	- Ensure consistency between implementation and documentation

	Before closing this issue:
	- Review and re-run workflow to verify all issues are resolved
	- Ensure changes maintain D7460N architecture principles

	---

	This issue was automatically created by the doc-architecture-enforcer workflow.

	# Reference:
	# - https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox
	# - https://developer.mozilla.org/en-US/docs/Web/CSS/:has
	# - https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role
	# - https://html.spec.whatwg.org/

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

AI Doc Consistency & Lint #20

Workflow file

AI Doc Consistency & Lint #20

Uh oh!

Jobs

Run details

Workflow file for this run