# Upgrade Alignment Pages

> Audit and explicitly upgrade generated alignment/*.html review pages to the current local alignment-page standard while preserving page-specific context

- Skill: `georgeqle/upgrade-alignment-pages` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add georgeqle/upgrade-alignment-pages`
- Raw SKILL.md: https://api.skillmd.com/api/skills/georgeqle/upgrade-alignment-pages/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: GeorgeQLe (https://skillmd.com/u/georgeqle)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/georgeqle/upgrade-alignment-pages

---


# Upgrade Alignment Pages

Invoke as `$upgrade-alignment-pages`.

Use this skill when a repository already has generated `alignment/*.html` review pages and the user wants to audit or update them against the current local alignment-page convention. This skill targets generated alignment HTML artifacts only.

## Inputs

- Default target repository: current working directory.
- Optional `--repo <path>` to target another repository.
- Optional explicit page paths under the target repository's `alignment/` directory.
- Optional `--apply`, or clear user wording such as "apply the upgrade" or "upgrade these pages", to allow page rewrites.

## Mode

- Default mode is audit/dry-run.
- The skill name alone is not apply intent; do not modify files unless the visible user request explicitly asks to apply or upgrade existing pages.
- In audit/dry-run mode, inspect pages and report drift without creating, editing, moving, or deleting any files.

## Process

1. Resolve scope:
   - Locate the project-root `alignment/` directory; stop if absent.
   - Enumerate `alignment/*.html`, excluding `alignment/index.html`.
   - If the user provided page paths, include only those paths after confirming they are inside the project-root `alignment/` directory.

2. Load local standards:
   - Read applicable local convention sources from `AGENTS.md`, `CLAUDE.md`, source `docs/alignment-page-convention.md`, packaged `assets/alignment-page-convention.md`, and legacy sibling `ALIGNMENT-PAGE.md` files found under `base/`, `packs/`, `.claude/skills/`, and `.codex/skills/`.
   - Treat those local files as read-only standards. Do not fetch external standards.
   - Extract the current required HTML behaviors: dark-mode styling, inline approval gates, section feedback controls, local section feedback YAML, unified response YAML, copy fallback behavior, unanswered-question handling, archive-before-replace behavior, and diff/change highlighting for updates.

3. Audit every selected page:
   - Read the whole HTML file before judging it.
   - Identify page-specific substance: title, meta/context, research findings, evidence/source matrices, assumptions, decisions, open questions, approval gates, review notes, proposed file changes, prior user feedback, and any page-specific scripts.
   - Report missing or stale standard features per page.
   - Classify each page as `current`, `upgrade-needed`, or `blocked-content-loss-risk`.

4. Stop on content-loss risk:
   - If a page's structure is too ambiguous to upgrade while preserving substantive content, do not rewrite it.
   - Report exactly what content could not be mapped and what human decision is needed.

4b. Batch-mode handoff (apply mode only):
   - Count pages classified as `upgrade-needed` (excluding `blocked-content-loss-risk`).
   - If count > 2:
     - Generate a phase in `tasks/todo.md` titled "## Phase: Upgrade Alignment Pages" with:
       - Execution Profile: serial
       - A Context block listing the standards sources discovered in step 2 and the archive timestamp path (`docs/history/archive/YYYY-MM-DD/HHMMSS/`)
       - One checklist step per upgrade-needed page: `- [ ] Upgrade alignment/<filename>.html — archive original, rewrite to current standard preserving all content, verify content preservation`
       - A final step: `- [ ] Run $compile-central-alignment and verify all archives; commit and push`
       - Acceptance criteria matching the audit findings
     - If `tasks/todo.md` already has unchecked items, append the phase at the bottom with a separator (`---`) and warn the user about pre-existing items.
     - Output the full audit report.
     - Report: "Generated exec-loop task plan with N steps. Recommended next route: approved task artifact"
     - Stop. Do not modify any HTML files.
   - If count <= 2: proceed to step 5 (inline apply).

5. Apply only when explicit:
   - Before replacing each page, archive the original to `docs/history/archive/YYYY-MM-DD/HHMMSS/alignment/<filename>.html`.
   - Rewrite the page contextually from the original, preserving page-specific research, decisions, questions, gates, review context, and user feedback.
   - Add or modernize missing standard elements without replacing the page with a generic template.
   - Preserve relative links and keep the page self-contained unless the original already used explicit external resources.
   - Highlight upgrade changes where useful with inline notes, a change summary section, or scoped diff styling.

6. Verify after apply:
   - Confirm every changed page has a matching archive copy.
   - Re-open each changed page textually and confirm the preserved title, decisions/findings, questions, and gates still exist.
   - Run or recommend `$compile-central-alignment` so `alignment/index.html` reflects updated page metadata.

## Audit Report

Include:

- Target repository and mode.
- Standards sources read.
- Pages inspected and pages excluded.
- Per-page status with missing standard features.
- Content preservation risks or blockers.
- In apply mode, archive paths and changed page paths.
- Verification performed.
- Next action: usually `$compile-central-alignment` after successful apply, or no mutation needed when all pages are current.
- In batch mode: the generated `tasks/todo.md` phase with execution steps and the approved-artifact route.

## Constraints

- Do not edit `CLAUDE.md`, `AGENTS.md`, any `SKILL.md`, or any bundled `ALIGNMENT-PAGE.md` file.
- Do not modify non-alignment HTML files.
- Do not modify `alignment/index.html`; leave index regeneration to `$compile-central-alignment`.
- Do not rewrite pages in audit/dry-run mode.
- Do not replace page-specific content with a generic template.
- Stop and report when an upgrade is likely to lose research, decisions, questions, gates, or review context.
- Do not create or modify GitHub Actions workflows.

## Default Shipping Contract

- **Audit mode:** no file mutations; no commit or push.
- **Apply mode (inline, ≤2 pages):** modified generated alignment pages and archive copies are normal repo artifacts. Follow the target repository's shipping rules after verification.
- **Apply mode (batch, >2 pages):** generates `tasks/todo.md` phase only; does not modify any HTML files. Commit the task plan, then stop; the approved task artifact records the next executable step.
- **Default next-step routing:** after successful inline apply, `Recommended next command: $compile-central-alignment`; after batch-mode handoff, `Recommended next route: approved task artifact`; otherwise report the audit result and recommend no follow-up skill when no upgrades are needed.